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HOW TO INTEGRATE SOFTWARE INTO THE CANON CAT 

Products designed by Information Appliance Inc. (IAI), such as 
the Canon Cat, have a number of unique features. One of them 
that directly affects third-party software development is the 
principle of editor-based software. 

In most microprocessor-based products, the user shifts between 
applications by returning to the operating system, indicated by a 
menu with a number of choices (or, equivalently , a window with a 
number of icons.) Then the user chooses the next application. 
Once having entered the application, the user gets the data on 
which to work. 

In an IAI interface, the data stays in place at all times so that 
the user can concentrate on content rather than on the system. 
As commands are given, different "applications" come to bear on 
the user's text or graphics (there are graphics primitives in the 
Cat, although the built-in software does not use them). This is 
possible due to cur unified data structure which is -- all at the 
same time — a text, a data base, a spreadsheet, and a 
programming environment. 

The user has a much simpler mental model with the IAI interface 
than with traditional products, since invoking an application 
looks just like another simple editor command. The user does not 
have to work with a number of different editors, one for each 
application. This is an improvement over the Macintosh, for 
example, in that with the Macintosh model each application must 
recreate (using provided routines) an interface that is similar 
to that of other applications. 

When developing new applications for the Cat, it is easiest, both 
on the programmer and the user, to make your application look 
just like the existing built-in software. When your application 
needs to get information from the user, it generally asks a 
question. This can be done by sending the question to the 
screen, perhaps surrounded by a few blank lines so that it is 
visible. If the user finds that the question has come out in an 
awkward place (say, in the middle of a letter) , then the user can 
always delete the question or move it elsewhere. 

A typical question for an accounting package might be: 

Name of account? 

When this appears , the application should wait for a response to 
be sent to it by the ANSWER command (USE FRONT-ERASE) . Thus the 
user is free to employ any and all the features of the Cat in 
creating the answer, for example, they might leap to their 
account area, or even change disks or perform a calculation to 
find the information they need. The idea here is to leave the 
full power of the Cat available at all times. 
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When the user has formulated the answer to the question your 
application has asked, they highlight it and use the ANSWER 
command. At this point, your application is in control again and 
can do what it wishes until it asks its next question. 

This "loss of control" after a question has been asked will 
disturb some designers who are used to a forcefully directed 
dialog with the user. However, research has shown that users 
work better if they can do tasks at their own speed, and if they 
are in control. There is nothing more annoying than a program 
that demands an answer and won't let you use the system (say for 
looking up a phone number you need right now) until you are 
finished answering the computer's question — a task that might 
take a few minutes if you have to look up something that's in a 
file cabinet somewhere. 

One secret of the Cat's utility is that all abilities are 
available simultaneously and instantaneously. If your 
application has a number of features or areas, then allow the 
user to create a message which activates them when desired (the 
messages sent to your application via the ANSWER command, of 
course. One set of messages might be: "AR" to activate the 
accounts receivable package, "AP" to activate the accounts 
payable package, and "GL" to run the general ledger package. 
Once in any of these packages, the dialog would work as already 
described. 

Notice that you do not have to write any I/O editing routines. 
You can simply send strings to the screen, and receive strings 
(edited by the user) . Naturally, your application may need to do 
error checking, but when an error is detected, you can just send 
a string to the screen with the message, the user can edit their 
previous response using the Cat's built-in editor, and resend it 
to your application. 

Following this protocol will keep the Cat feeling like a Cat, and 
will be least disruptive to a user's habits. It is also very 
easy and quick to create application interfaces this way. 

Jef Raskin 
13 September 1988 
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INTRODUCTION/BACKGROUND 

BACKGROUND OF FORTH 

The Forth language was developed in the early 1970' s by Charles 
"Chuck" Moore. It was designed for control applications in an 
astronomical laboratory environment. Forth' s interactive nature 
and its extremely small "kernel" of basic words (the Forth kernel 
typically requires only 2-5K bytes of memory) made it ideal for 
machine control using the very limited minicomputers of the time. 

tFORTH 

The intent of this manual is to describe the "tForth" 
("token- threaded Forth") implementation of Forth designed 
specifically for use in the Information Appliance Inc. Cat 
project. The basics of Forth and Forth programming are not 
covered in a comprehensive manner. Starting Forth includes very 
good explanations of basic Forth programming and good 
descriptions of the inner structure of a simple Forth. 



ORGANIZATION OF THIS MANUAL 



This manual is organized as follows: 



Introduction: 



A very brief, general overview of the Forth 
language. This section tries to give the reader 
a feel for the Forth language by presenting 
examples and discussion of interactive and 
compiled execution of Forth words and parameter 
stack usage. 



tForth How to program in tForth. Examples are used to 

Programmer demonstrate how common programming tasks 
User Manual (arithmetic, memory access, character and 
numeric I/O, control structures, constants, 
variables, etc.) are performed in tForth. This 
section will give the reader a quick 
introduction to the use and power of tForth. 



tForth 
Technical 
Reference 
Manual 



tForth 

68000 

Assembler 



Implementation-specific information required by 
those who intend to change or extend the tForth 
system. Topics covered include system memory 
usage, the vocabulary and dictionary structure, 
compilation and token- threading specifics. 

How to use the tForth 68000 Assembler. 



Glossaries 



Stack notation and short descriptions of the 
words included on the tForth source disks. The 
words are grouped according to function (there 
is a list of functional groups at the start of 
the Glossary) . The words are arranged 
alphabetically within in each group. 



Appendices 



Program listings. 
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ENABLING FORTH IN THE CAT 

Forth is normally hidden away, inaccessible in the Cat. However, 
with a simple incantation you can "enable Forth," making it 
possible to switch from the Cat's editor to a Forth programming 
environment, or to run Forth programs from the tat's editor with 
the ANSWER command. Forth enablement is associated with a given 
disk and text. If you enable Forth, record the text, change to a 
non-enabled disk, then Forth will no longer be enabled. 

Remember to exercise caution whenever Forth has been enabled. 
For example, a nonprogrammer may be trapped in Forth if they 
accidentally press the key combination SHIFT-USE FRONT-SPACE BAR 
while editing the text on a Forth-enabled disk. The key 
combination USE FRONT-SEMI-COLON will erase the disk in the drive 
if Forth is enabled. Other pitfalls exist. SO, PROCEED WITH 
CAUTION IF YOU ENABLE FORTH. READ THE DISCLAIMER AT THE 
BEGINNING OF THE MANUAL. 

How to Turn on Forth 

We will now explain how to turn on Forth, and, equally important, 
how to turn it off: 

1. To turn on Forth in a Cat, type the following phrase (be sure 
to capitalize "E", "F", and "L"): 

Enable Forth Language 

2. Highlight these three words. 

3. Hold down the USE FRONT key and, while holding it, tap the 
ANSWER key (ERASE). Then let go. This executes the ANSWER 
command, enabling Forth. You are not yet in Forth. 

k. Now hold down the USE FRONT key AND the SHIFT key, and, while 
holding BOTH keys, tap the SPACE BAR. You are now in the 
Cat's Forth editor. 

5. Type the following and press the RETURN key (the letters will 
automatically appear in boldface) : 

-1 wheel! savesetup re 

This step allows you to enter Forth simply by pressing 
SHIFT-USE FRONT-SPACE BAR from now on. 

To enable easy access to Forth with Step 4 only, make some 
change to a Setup parameter, then use the DISK command. This 
will save the Forth enabling information on the disk. 
Whenever you play back this disk, you can then enter Forth 
using only the procedure of Step 4. 
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6. To turn off Forth, type the following and press RETURN key: 

Forth? off wheel! re 

Make some change to a Setup parameter, then use the DISK 
command. This restores the Cat to normal operation, meaning 
that you will have to start over at step 1 again to invoke 
Forth. Normal Cat users will not be trapped in Forth in case 
they happen to accidentally press SHIFT-USE FRONT-SPACE BAR. 
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TALKING TO tFORTH 

tForth is hiding in the background of every Cat system. It is 
very easy and convenient to communicate with tForth from within 
the editing environment. 

Sending Commands to tForth 

Once Forth has been enabled (see the previous page), commands and 
programs can be sent to tForth from the editor by highlighting 
the desired command string or program listing and pressing 
[ERASE] while holding the [USE FRONT] key down. tForth' s 
responses will be printed out in the editor. 

All examples in this manual are expected to be typed into the 
editor and "sent" to tForth in this manner. All examples 
presented are set off from the body of the text by two blank 
lines and are indented: 

3 dup . .33 

A section of the above example was underlined. In an example, 
the underlined sections are the sections of the text which should 
be highlighted and passed to tForth by pressing the [USE 
FRONT] [RETURN] key combination. After the above example was sent 
to tForth, tForth responded by printing two 3 ! s on the screen. 

Using the Calc Command to Talk to tForth 

Commands and programs can also be sent to tForth with the use of 
the [USE FRONT] [CALC] key combination. When this method is 
used, all command strings or program listings sent to tForth must 
be preceded by a "]" character: 

]3 dup . .33 

The above example produced the same results as the [USE FRONT] 
[RETURN] example. The [USE FRONT] [CALC] method is not used in 
this manual. 

Errors 

The [USE FRONT] [RETURN] is used to let Forth know it should start 
•processing' any highlighted words. If Forth ever has a problem 
processing an input, a beep will be issued. To see the error 
message press the [EXPLAIN] key while holding the [USE FRONT] key 
down. For example, if tForth is sent the following input: 

How now brown cow? 
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it will beep and [USE FRONT] [EXPLAIN] will reveal a "can't use" 
message. This is the error message which occurs when tForth is 
sent a command it does not recognize. 

CAUTION: ALWAYS RECORD YOUR EDITOR TEXT ON DISK BEFORE DIRECT 
EXECUTION OF tFORTH WORDS. IT IS VERY EASY TO MAKE PROGRAMMING 
MISTAKES WHICH COULD PERMANENTLY DAMAGE THE DOCUMENT. 
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A BRIEF INTRODUCTION TO FORTH 

The Forth language is comprised of many "words" (commands). This 
collection of words is referred to as the "Forth dictionary." 
The tForth dictionary contains approximately 600 words. The list 
below shows a few Forth words and the actions they perform: 

emit Takes a number and displays the corresponding 

ASCII character on the screen. 

/ 
+ Adds two numbers together and returns the 

result. 

words Produces a listing of all available words. 

if Words used to implement the IF... THEN 
then program control construct. 

@ Fetches a 32-bit value from memory. 

As the list shows, a Forth word can either have the format of a 
'normal 1 word {a sequence of letters), or it can be a punctuation 
mark, a sequence of punctuation marks, or a mixture of 
punctuation marks and characters. In a Forth program, all words 
must be separated from each other by at least one space, tab, or 
carriage return. In this document Forth commands will be shown 
in boldface. For example: 

"The Forth word words will produce a listing of all available 
words . " 

Note: tForth is case-sensitive. This means that tForth thinks a 
capital W is different than a lowercase w. Thus tForth will 
think Words is a different command than words. 

If the pronunciation of a Forth word is unclear, it's first usage 
in the text will be followed by the natural language 
pronunciation enclosed in quotes and parentheses. For example: 

To take a number off of the parameter stack 
and display it, use the word . ("dot"). 

Executing a Forth Word 

Most of the words in the Forth dictionary may be executed 
directly and immediately, from the keyboard. The example below 
shows how the Forth word emit could be used to display an 
asterisk character on the screen. In the example, the underlined 
type is used to indicate which commands should be highlighted and 
sent to tForth. The normal type is used to show Forth 's 
responses . 
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Note: Do not confuse the underlined commands in the examples 
with the underlined Forth words in the text. In the examples the 
underlined commands are those commands which should be 
highlighted and sent to tForth with the ANSWER command. 

42 emit * 

emit , as was described above, is a Forth word which will display 
the character which corresponds to the ASCII value passed to it. 

Compiling Forth Words 

The interactive execution of emit in the previous example did not 
cause any code to compiled. The Forth word : ("colon") is used 
to turn the Forth compiler on: 

: printstar 42 emit ; 

The above example shows how a new word may be added to the Forth 
dictionary. The word which immediately follows : (printstar 
in the above example) is the name which will be assigned to the 
new word. The Forth words following the name and preceding the 
; will be compiled into the new definition; these are the words 
which define the actions of the new word. Since the action words 
for printstar are 42 emit, printstar will print an asterisk when 
executed. The word ; ("semi-colon") is used to turn the compiler 
off and return to the interactive execution mode. 

Note that in this example, sending the input to Forth did not 
cause the asterisk to be displayed. Since the Forth compiler was 
"on" when the "42 emit" was typed, the 42 emit was compiled 
rather than executed. Forth was able to successfully compile the 
new definition so no error beep was issued. Forth is an 
"incremental compiler"; code is compiled definition by 
definition; compilation is triggered by each reception of a line 
of input. 

The Forth Parameter Stack 

Forth is a stack-based language. Any Forth word which takes an 
input will expect to find its input parameter on the Forth 
parameter stack when it executes. Any Forth word which returns a 
value will leave the value on the parameter stack when it 
completes execution. 

The parameter stack, and stacks in general, are functionally 
similar to the spring-loaded stack of plates which can be found 
at most institutional kitchens. Whenever a plate is taken from 
the stack, it is always taken from the top of the stack of 
plates. Whenever a plate is added to the stack, it is always 
added to the top of the stack of plates. A person who does not 
want the steaming hot plate on top of the stack must remove the 
top plate before the second plate can be accessed. If no plates 
are available, the stack is empty. 
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The Forth parameter stack works the same way as the stack of 
plates, except the Forth parameter stack is set up to hold 
numeric values rather than plates. Also, just as the kitchen 
stack was designed for a certain plate size, the Forth parameter 
stack is designed for a certain numeric value size {the plate 
size of the tForth parameter stack will be discussed later) . 

Interacting With the Parameter Stack 

To put a number on the parameter stack, send the number to Forth: 

3* 

To take a number off the parameter stack, use the word drop. To 
take a number off the parameter stack and display it, use the 
word . ("dot"): 

. 34 

To place more than one number at a time on the stack, send the 
numbers, separated from each other by a space or spaces (so that 
Forth knows they are distinct numbers) , to Forth: 

3 6 8 

Now there are three numbers on the stack. If . is used, it will 
take the top number off the stack and display it. Since the 8 
was the last value placed on the stack, it will be the top value 
on the stack: 

. 8 

To place more than one number on the stack at a time, the numbers 
were separated by spaces and sent to Forth. This is the same way 
Forth commands (words) work. To take both of the remaining 
numbers off the stack, the word . can be used twice on the same 
line: 

..63 

Forth 's response should be read left to right. The 6 is the 
result of the first use of . The 3 is the result of the second 
use of 

Note what happens if . is used again: 

. 

You should hear a beep as . tried to remove a value from an 
empty stack and Forth responded by displaying a zero, beeping and 
issuing a "stack is empty" error message. 
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Passing Parameters to Forth Words on the Stack 

Many Forth words take input parameters from the stack and return 
results on the stack. The Forth word ♦ ("plus") is a good 
example of such a word: 

5 4 ♦ . 9 

+ takes two numbers from the stack (the 5 and the k in the above 
example), adds them together and returns the single number result 
on the stack. In the example, . was use to display the result 
returned by + 

Summary 

* Forth programs are developed by creating new 
words out of previously existing words. 

* The parameter stack is the primary means of 
communication among Forth words. 

* The Forth language does not have many syntax 
requirements. This gives the experienced programmer 
great control over the computer but can make it 
difficult for beginning programmers to locate mistakes. 

* The interactive abilities of Forth make it a hard-to-beat 
debugging environment. Each word can be tested 
individually and interactively. 

This is the end of our brief introduction to the Forth language. 
For more introductory Forth reading, refer to the first chapter 
of Starting Forth , by Leo Brodie (Prentice-Hall, Inc., Englewood 
Cliffs, NJ 07632, 1981). 
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tFORTH PROGRAMMER USER MANUAL 



INTRODUCTION 

Now it's time to actually try some tForth programming. tForth 
contains words for performing many types of programming tasks. 
The available tForth words may be grouped into 19 functional 
categories: arithmetic words, stack manipulation words, 
character I/O words, numeric I/O words, structured programming 
words, etc. A complete list of these categories is shown at the 
start of the tForth glossary section, and the words in the 
glossary are grouped according to these functions. 

This section of the manual will concentrate on describing how a 
few words from the most important functional categories are 
used. The categories covered will be: 

* Vocabularies 

* Stack Operators 

* Integers 

* Program Control Structure Words 

* Character I/O Words 

* Numeric I/O Words 

* Local Variable Words 
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MOVING AROUND IN tFORTH -- VOCABULARIES 

Before tForth programming can commence, the 'layout' of the 
tForth dictionary should be explained from a user's point of 
view. The words in the tForth dictionary are arranged into four 
groups of words called 'vocabularies'. The names of the four 
initial tForth vocabularies are forth , user , function , and 
arithmetic . The diagram on the following page demonstrates the 
relationships between the four initial tForth vocabularies. The 
forth vocabulary is the main or 'root' vocabulary. The three 
other vocabularies branch out from forth (the new vocabulary 
should be ignored for now), i.e., forth is the parent vocabulary 
of user . 

existing is a Forth word which will print out the names of all 
existing vocabularies, the names of their parent vocabularies, 
and a count of how many vocabularies may still be added to the 
system: 

existing 

function (in forth) arithmetic (in forth) user (in forth) 

forth (in forth) 12 free y 

Note: There is also a fifth initial vocabulary which is 
invisible to the user and is named, appropriately, hidden . The 
hidden vocabulary contains the words used to implement the Cat 
editor. 

The Vocabulary Search Order 

In order for tForth to compile or execute a word, it must be able 
to find the word in the tForth dictionary. The programmer helps 
tForth find words by setting up a 'vocabulary search order'. The 
vocabulary search order is a list which tells tForth which 
vocabularies it should search through and in which order the 
vocabularies should be searched. The word searched displays the 
current search order: 

searched user forth arithmetic function 

The names indicate which vocabularies are being searched, and the 
order of the names, read from left to right, indicates the order 
in which the vocabularies are searched. 

Modifying the Search Order 

A vocabulary may be added to the front of the search order by 
executing its name. If the vocabulary was already in the search 
order, executing its name will place it first in the search 
order. For example, to have the forth vocabulary searched first: 

forth 

searched forth user arithmetic function 
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The tForth Vocabularies 







arithmetic 
vocabulary 



user 
vocabulary 



hidden 
vocabulary 



forth 
vocabulary 



function 
vocabulary 



To remove a vocabulary from the search order use the word 
deactivate 

deactivate arithmetic 
searched forth user function 

Listing the Words in a Vocabulary 

The tForth command words can be used to print a listing of all 
words in the first vocabulary in the search order: 

forth 

words 

! Ichar !csp Iptr " "to # ##ichrs Mind ##wide ##lt 
##sp ##tabs #wd #> lab #be #chars #chrs #cmptabs 
#count #ctrl #formats #guard #ichrs #indent #iwide 
#learns #left #limit #line llmar #lnloc #long #nextwrap 
<cr> ok 

The word forth was used to place the forth vocabulary first in 
the search order. y 

The words listing may be terminated by pressing any key. In the 
example, the carriage return key was used to prematurely 
terminate the listing. Since most of tForth* s 600 words are 
located in the forth vocabulary a complete listing of all words 
in the vocabulary would be dull reading (masochists, however, are 
encouraged to display the complete listing at their terminals) . 

The words in a tForth vocabulary are arranged alphabetically. 
This allows tForth to locate words in the vocabulary with a very 
quick binary search algorithm. In most Forths the words are 
arranged in a chronologically ordered linked list. New words are 
added to the beginning of the vocabulary list. Locating a word 
in linked list requires that the list of words be searched 
linearly, starting from the newest word and progressing through 
the list to the oldest added word. 

If you have been reading Starting Forth you should recognize a 
few of the words ( ! and #> ) in the listing above. The 
unfamiliar words are additional Forth words which were not 
described in Starting Forth . 

Adding New Words to a Vocabulary 

New words may only be added to the current "open" vocabulary. 
Only one vocabulary may be open at a time. The word addto is 
used' to open a vocabulary so that words may be added to the 
vocabulary. When addto is used, it is followed by the name of 
the desired vocabulary; in each case, here points to the next 
available byte of dictionary space (see page 70 for more on 
addto) . 
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Note: The user vocabulary is the vocabulary to which all new 
"user-defined" words should be added. The function and 
arithmetic vocabularies are used by the editor so they should not 
be altered. The words in the forth vocabulary are located in 
EPROM so it is not possible to add words to the forth vocabulary. 

The example below shows how a new word is added to the user 
vocabulary. The phrase 'addto user* opens the user vocabulary 
so that new words may be added. The previous open vocabulary is 
closed. 

printchar is a word which performs the same functions as the 
printstar word defined in an example in the introduction. 

To reiterate the earlier description of compilation, the Forth 
word : turns the Forth compiler on. The word ]which immediately 
follows : will be the name for the new word. The characters 
between the left and right parens form a comment string I (Forth 
commenting style will be discussed later) . All other words 
between the definition name and the final semicolon are compiled 
into the new definition. When the definition is later executed, 
these compiled words will be run. 

addto user 



printchar ( 



Prints a character. ) 42 emit 



Now that printchar has been compiled, words can be used to ensure 
that printchar was really added to the user vocabulary: 



user 



words 
printchar 



( Make user the current vocabulary ) 

( and then use words to list the words ) 

( in the current vocabulary. ) 



The word printchar is the only word in the user vocabulary. 
(Note: If you have been experimenting with your system, your 
user vocabulary may have additional words) . The new word may be 
executed interactively by typing its name followed by a carriage 
return: 



printchar * 

A Short Program 

The program below is taken from page 13 of Starting Forth , 
prints a large letter "F" using asterisk characters. 



It 



The word decimal tells Forth that all numbers input from this 
point on are to be treated as decimal numbers, addto user opens 
the user vocabulary. The program is comprised of the five 
definitions above, and the printchar definition which was 
compiled earlier. The program was developed by first writing the 
three lowest level words: printchar , printchars , and margin. 
Next, two intermediate words, blip and bar , which use the three 
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lower level words, are defined. Finally, the highest level word, 
F , which uses the two intermediate words, is defined. Since 
Forth programs continually build upon themselves, the order in 
which words are defined is extremely important. A word canuot be 
used in a new definition unless the word has been previously 
defined. 

The program is run be executing the highest level word F (use 
uppercase "F" ! ) . 

addto user 
decimal 

: printchars ( -> n | Prints n asterisks. ) 
do printchar loop ; 

: margin ( -> | Prints a carriage return and 30 spaces. 
cr 30 spaces ; / 

: blip ( -> J Prints 30 spaces followed by an asterisk ) 
margin printchar ; 

: bar ( -> | Prints 30 spaces followed by 5 stars. ) 
margin 5 printchars ; 

: F ( -> I Prints a large letter 'F'. ) 
bar blip bar blip blip cr ; 



***** 

* 
***** 

* 
* 

Redefining a Word (Changing the Actions of a Word) 

After a word has been defined, the action of the word can be 
altered by 'redefining' the word, i.e., entering a new colon 
definition which has the same name as the word to be replaced. 
For example, to change the action of printchar: 

: printchar ( -> | Prints an '§'. ) 
64 emit ; redefining printchar 

Whenever tForth compiles a new definition, it looks at the names 
of all other words in the open vocabulary to see if a word with 
the same name already exists. If a word with the same name does 
exist, the compiler knows that the word is being redefined. 
Instead of creating a new entry in the vocabulary for the word, 
the compiler will replace the old actions of the word with the 
new actions. The message redefining <name> will be issued 
whenever a word is redefined. 
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This new version of printchar will print a '@' instead of a ' *' 
when executed. All other words which referenced printchar will 
also be affected by this change: 



@ 

e 
e 

How Words Are Redefined in Other Forths 

In most Forth *s the redefinition of a word causes a complete new 
entry to be added to the dictionary. Because the vocabulary list 
is searched from newest entry to oldest entry, the redefined 
version of the word will be found before any previous versions of 
the word in all future dictionary searches. For example, if the 
word printchar had been redefined in most other Forths, any word 
defined later which referenced printchar would always use the 
redefined version of printchar. However, any words defined 
BEFORE printchar was redefined would ALWAYS reference the 
original, obsolete version of printchar. 

In tForth, programmers can alter the actions of definitions 
without leaving unused, obsolete code in the dictionary. Every 
word in a program will always reference the most up-to-date 
versions of other words in the program. 

Purging a Word From the Dictionary 

The tForth word purge can be used to remove any word, regardless 
of vocabulary, from the dictionary (remember that the words in 
the forth vocabulary cannot be altered because they are in 
EPROM) . The example demonstrates how printchar could be removed: 

purge printchar 

What about the words which referenced printchar? Let's execute F 
to see what happens: 



(X) 

Your cursor should have stopped at the point marked by the ' (X) * 
above (you shouldn't see the '(X)' though) and a beep and the 
error message "unassigned token" should have been issued. 

The first word run when F was executed above was bar (refer to 
the program listing) . The first word in bar was margin . 
margin did not reference printchar so it executed without error 
and printed a carriage return and 30 spaces. The next word in 
bar was printchars , a word which did reference printchar . As 
soon as printchars tried to execute printchar , tForth displayed 
an error message which indicated that it could not find the word 
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it was supposed to execute next. This situation can be remedied 
by defining a new word named printchar : 

: printchar ( -> | Print a character. ) 
70 emit ; 

This time the redefining printchar message was not issued because 
there was no word named printchar in the vocabulary at the time 
the definition was compiled. Now F can be successfully executed: 



FFFFF 

F 

FFFFF 

F 

F 

Creating New Vocabularies 

The word vocabulary is used to create new, named vocabularies. 
The new vocabulary will be empty and inactive (closed) . The 
parent vocabulary for the new vocabulary will be the vocabulary 
which was open when the new vocabulary was created: 

add to user 
vocabulary testvocab 

existing testvocab (in user) function (in forth) 

arithmetic (in forth) user (in forth) forth (in forth) 11 free 

testvocab words 

In the example, a new vocabulary named testvocab was created. 
Since the user vocabulary was open when testvocab was created, 
the user vocabulary is the parent vocabulary of testvocab . This 
relationship was verified above by using existing to print a 
listing of all of the vocabularies and their parent vocabularies. 

Next, words was used to verify that testvocab was empty when it- 
was created. 
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THE PARAMETER STACK 

In Forth, the programmer places the parameters on the stack and 
then executes the word. The word is responsible for taking the 
parameters it requires from the stack. If the word returns any 
parameters, it will leave them on the parameter stack. The 
programmer is responsible for removing any parameters returned 
from the stack. For example, consider the addition of 3 and 4, 
and the display of the sum: 

3 4 ♦ • 7 

First, the parameters 3 and 4 are placed on the stack by entering 
the numbers separated by spaces. Next, the addition command + 
('plus') is executed. + takes the 3 and the 4 off the stack, 
adds them together, and leaves the result (7) on the stack. The 
word . takes the result off the stack and displays it. 

Structure of the Parameter Stack 

The diagram on the following page uses interlocking blocks to 
depict the functioning of the tForth parameter stack. The tForth 
parameter stack can hold up to 48 parameters. During execution 
of a program, only 5~10 parameters are typically on the stack at 
one time. 

The parameter stack grows downward in memory. The word spO 
{'s-p-zero') returns the address of the base of the parameter 
stack. The word sp@ ( 's-p-fetch' ) returns the address of the top 
item on the stack. Each parameter placed on the stack is placed 
in successively lower memory locations. 



spO 
sp§ 



4 
sp@ 



286748 
286748 



sp@ . 286744 



286740 



The stack is empty so both ) 
spO and sp@ return the ) 
same address, the address ) 
of the base of the stack. ) 

Place one item on stack. ) 

Now sp@ points at the top item ) 
on the stack, which is located ) 
4 bytes lower in memory than ) 
the base of the stack. ) 

Place another item on the stack. ) 

sp@ has been decremented by ) 
4 bytes again. ) 



Notice that each time a parameter was added to the stack, the 
address returned by sp@ (also called the 'stack pointer') is 
decremented by 4. This is because the tForth parameter stack is 
4 bytes wide. Each item on the stack is a 4 byte, or 32-bit, 
value. This means the largest signed number which can be placed 
on the tForth parameter stack is 7FFFFFFF (hexadecimal) . 
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The tForth Parameter Stack 



st ack base | spO,sp@ | stack base spO 



Room for 48 parameters 



Tjr-y 

upper Srott 



3 
4 



sp@ 



Room for 46 parameters 





Room for 47 parameters 




An empty stack. 



Two items on the stack. 



One item on the stack. 



Since one bit is used for the sign bit, this is the largest 
number which can be expressed with 31 bits. 

tForth Is a 32-bit Forth Implementation 

Because of the stack width, tForth is categorized as a 32-bit 
Forth implementation. A 32-bit Forth fits well on the 68000 
microprocessor with its internal 32-bit wide data path and 32-bit 
general purpose registers. Most of the current Forths, including 
the Forth described in Starting Forth , are 16-bit Forths since 
32-bit microprocessors have only recently become widely available. 

Observing the Stack 

Most Forth words either put values on the stack or remove items 
from the stack, .s is a word which displays the contents of the 
stack without disturbing the contents: 

3^56. s 3^56 

Since .s does not disturb the stack in any way, it is a very 
handy tool for checking results. Another useful stack checking 
word is depth . depth returns a count of the number of items 
currently on the stack: 

depth . k ( There are four items on the stack. ) 

. 6 5 4 3 ( Take the four values off of the stack. ) 
depth . ( Now the stack is empty. ) 

tForth Words Which Operate on the Stack 

In the glossary, the tForth words which operate on the parameter 
stack are grouped together under the 'Stack Manipulation* 
heading. The stack manipulation words are used to rearrange, to 
duplicate, to remove, and to check items on the parameter stack. 

Here are some examples of the use of some of these stack 
manipulation words. The diagram on page 23 has a visual 
demonstration of the effects of these examples on the stack: 
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2 3 4 

.s 2 3 k 



swap 
rot 



.s 2 4 3 
s 4 3 2 



( Put three items on the stack. ) 

CHECKING THE STACK ) 

Display the items on the stack ) 

without removing them from the stack. ) 

REARRANGING STACK ITEMS ) 

Move the second stack item to the top. } 

Move the third stack item to the top. ) 



over . s 



4 3 2 3 



dup 



43233 



DUPLICATING STACK ITEMS ) 

Copy the second item on the stack. ) 

Leave the copy on top of the stack, ) 

( Copy the top item on the stack. ) 
Leave the copy on top of the stack. ) 

REMOVING STACK ITEMS ) 
drop .s 4 3 2 3 ( Discard the top stack item. ) 

Simple Words Which Use the Stack 

The words which perform the basic arithmetic operations: 
addition, subtraction, multiplication, and division, are all 
simple words which use the stack. These simple operators have 
been grouped under the "Arithmetic Operators" headings in the 
glossary. Here are some examples of their use: 

Here is the name, pronunciation, and stack notation for each word 
used below: 



+ ( nl n2 - n3 ) 

1+ ( nl - n2 ) 

- ( nl n2 - n3 ) 

2- ( nl - n2 ) 

* ( nl n2 - n3 ) 

2* ( nl - n2 ) 

/ ( nl n2 - n3 ) 

2/ ( nl - n2 ) 
mod ( nl n2 - n3 ) 



2 3 

+ 

.s 5 

1+ 
.s 6 



'plus'} 
'one-plus' ) 

' minus ' ) 

' two-minus ' ) 

' times' ) 

' two-times' ) 

'divide') 
' two-divide' 



ADDITION ) 

Put two numbers on the stack. ) 

Use + [ ' plus ' ] to add the numbers . ) 

Display the result. ) 

Add 1 to the number on the stack. ) 
Display the result. ) 



(cont. ) 
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9 6 



• s 3 

2- 

. 1 



2 


4 


« 




.s 


8 


2* 






16 



50 

/ 


3 


.s 


16 


2/ 




.s 


8 


5 mod 


# 


3 



SUBTRACTION ) 

Put two numbers on the stack. ) 

Use - [ ' minus ' ] to subtract the top ) 

number on the stack from the second ) 

number on the stack: 9 ~ 6 = 3 . ) 

Display the result. ) 

Subtract 2 from the number on the stack. ) 
Remove the result from the stack and ) 
display it. ) 

MULTIPLICATION ) 
Put two numbers on the stack. ) 
Multiply the two numbers. ) 
Display the result. ) 

Multiply the number on top of the stack ) 
by 2. ) 

Remove the result from the stack and ) 
display it. ) 

DIVISION ) 

Put two numbers on the stack. ) 

Divide the second number on the stack ) 

by the number on top of the stack: ) 

50 / 3 = 16 . ) 

Display the result. ) 

Divide the number on top of the stack ) 

by 2. ) 

Display the result. ) 

Divide the number on top of the stack ) 
by 5 arid return the remainder. ) 
Remove the remainder from the stack and ) 
display it: 8/5=1 . remainder = 3 • ) 
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Manipulating the Stack 

Examples are cumulative 



2 
z 

4 



c 



2 

4. 
3 




initial stack 



after swap 



after fjoj 




4 

i 

2 
3 



c 



2 
2 

3 

3 




4_ 
3_ 
2 
3 




after over 



after dup 



after drop 



All of these words take one or two numerical inputs, perform an 
arithmetic operation upon the input (s), and return a numerical 
result on the stack. However, as will be shown below, the stack 
does not have to be used for numerical values only. 

Comparison Operators and Flags 

The tForth comparison operators are another group of simple words 
which use the stack. The comparison operators treat their inputs 
as numbers and return a flag as a result. A flag is a value 
which may only represent one of two states: "true" or "false". 
In general, tForth treats any non-zero flag as a true flag and 
any flag with a value of as a false flag. All of the words 
listed under the "Comparison Operators" section of the glossary, 
except the words max and min , will return a specific 
non-zero value, '-1', if the result of their operation is true 
and will return *0' if the result of their operation is false. 
Here are some examples of comparison operator use. 

Here is the name, pronunciation, and stack notation for each 
comparison operator used below: 



0< 


I n - f } 


[ ' zero-less-than* 


0= 


n - f ) 


' zero-equal ' ) 


= 


nl n2 - f ) 


'equal 1 ) 


<> 


nl n2 - f ) 


'not-equal' ) 


< < 


; nl n2 - f ) ( 


'less-than' ) 


> ( 


; nl n2 - f ) < 


'greater- than' ) 



inrange ( nl n2 n3 - f 

max ( nl n2 - n3 ) 
min ( nl n2 - n3 ) 



3 0= 
-2 0< 



<> 

< 

> 



-1 



-1 
, 


-1 



5 2 8 inrange . -1 



4 8 max 
4 8 min 



SINGLE PARAMETER COMPARISONS ) 
False, 3 is not equal to 0. ) 
True, -2 is less than 0. ) 

DOUBLE PARAMETER COMPARISONS ) 
True, 3 is equal to 3. ) 
False, 3 and 3 are equal. ) 
False, 6 is not less than 3« ) 
True, 6 is greater than 3- ) 

TRIPLE PARAMETER COMPARISONS ) 
True, 2<=5<=8 ) 

8 is the larger of 4 and 8. ) 
4 is the lesser of 4 and 8. ) 



Note that the max and min comparison operators are the only 
ones which return numbers instead of flags. 



- 25 - 



Forth Is Not a "Typed" Language 

In many languages, the type of each program parameter must be 
declared. If a parameter is a number it must be declared to be 
of type byte, integer, long, real, signed, unsigned. If a 
parameter is declared to be of type address or flag, it can only 
be used by functions which operate on addresses or flags. A 
language which requires typed parameters can help the programmer 
avoid mistakes since it is constantly cross checking actual input 
parameter types with the allowed input parameter types for a 
given operation. 

The Forth language does not enforce typed parameters. Any type 
of item (number, address, flag) may be placed on the parameter 
stack. Since all Forth words can use the parameter stack, it 
follows that all Forth words can accept any type of input 
parameter. 

There are both advantages and disadvantages to non- typed 
languages: 

DISADVANTAGES 

* A non- typed language cannot help the programmer by 
double checking all input parameters used. 

* It is difficult for code written in non-typed languages 
to be shared since the types of the input and output 
parameters being used is usually not easily determined by 
the reader of the program listing. 

ADVANTAGES 

* A program written in a non- typed language should 
execute faster than a program written in a typed 
language because all of the code required for 
parameter checking is removed. 

* A non- typed language gives the programmer the 
extra control over the language which is often required 
to get more performance out of a computer. 

In Forth, as in any language, the second disadvantage above can 
be overcome by interspersing useful, thoughtful comments 
throughout the program code. The Forth community has taken the 
commenting solution a step farther by developing a suggested 
Forth commenting style which has been widely accepted. This 
commenting style, called 'stack notation' is discussed next. 
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STACK NOTATION 

Stack notation is a standard method of commenting the stack usage 
of Forth words. For example: 

< ( nl n2 - f ) 

This is the stack notation for the word < ( 'less- than* ) . The 
word ( { 'left-paren 1 ) is a Forth commenting word. Because ( is a 
Forth word, it must be surrounded on either side by at least one 
space or tab. Any characters "in a Forth program which lie 
between parentheses are considered to be comments and are ignored 
by the Forth compiler. The characters between the parentheses 
above comprise the stack notation for < . 

In stack notation, characters to the left of the ' -' are used to 
indicate the inputs a Forth word expects to find on the parameter 
stack when it starts execution. Characters to the right of the 
'-' are used to indicate the outputs a Forth word will leave on 
the parameter stack when it completes execution. 

In stack notation, the following codes are used to indicate 
parameter types: 



CODE 



MEANING 



HEXADECIMAL RANGE 



Boolean flag 

7-bit ASCII 
character 



= false, non-zero = true 
0...7F 



unsigned 8-bit 
number 



O...FF 



unsigned 16-bit 
number 

signed 32-bit 
number 



0...FFFF 



-80000000. . .7FFFFFFF 



u 



unsigned 32-bit 
number 



0...FFFFFFFF 



a 32-bit address 0...FFFFFFFF 

Here are other examples of stack notation. Note that a digit 
suffix is used to differentiate multiple parameters of the same 
type: 



words ( 



) 



( words takes no inputs and returns no ) 
{ outputs. ) 



fill ( a u b - ) ( fill takes three inputs and returns no ) 

( outputs. ) 
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key { - c ) ( key takes no inputs and returns one ) 

( output . ) 

♦/mod ( nl n2 n3 - n4 n5 ) 

( */mod is a word which accepts multiple ) 
{ numeric parameters. Digits are used ) 
( the ' n' code to differentiate the ) 
( parameters. ) 

-trailing { a n - a n' ) 

When an output parameter is followed immediately by an 
apostrophe character it means the output parameter is a slightly 
modified version of an input parameter, rather than a completely 
new parameter. For example, -trailing takes as inputs a string 
address (a) and the length of the string (n) . -trailing strips 
any trailing spaces from the string and returns the new, adjusted 
length of the string (n* , pronounced 'n-prime'). 

tForth Stack Notation 

In tForth, the stack notation structure has been slightly 
extended to include comments: 

c, ( b - | Compile byte b at here. ) 

The ' | * marks the end of the normal stack notation and the start 
of the comment field. The comment field can be as long as 
necessary (multi-line) as long as it is terminated by a closing 
paren. 
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INTEGERS AND MEMORY OPERATORS 

Variable data is program data whose value changes during 
execution of a the program. Constant data is program data whose 
value will remain constant throughout program execution. For 
example, the equation used to calculate the area of a circle is a 
familiar equation which makes use of both constant and variable 
data: 

(PI) * (radius, squared) = area 

(100*PI) * {[radius (meters)] ~2} = area (cm ~2) 

The ' (100*PI) f or * (100*3.14 = 314) ' , is the constant in the 
circle area equation. The radius is the variable data. Scaling 
is used (the PI value is multiplied by 100 to eliminate 
fractional values) to ensure that only integer values are 
required. 

Forth Note: Most Forth implementations do not support floating 
point number input/output or floating point math calculations. 
Many Forth designers /programmers feel that any floating point 
operation can be implemented using integer math with the proper 
scaling and that the integer math operations will be faster and 
more compact than their floating point counterparts. 

Declaring Constant and Variable Program Data 

The tForth word integer is used to define and name both 
constant and variable program data. The general format for the 
use of integer is: 

<value> integer <name> 

<value> is the 4 byte value for and <name> is the name of the 
constant or variable data, integer makes <name> an executable 
Forth word. Whenever <name> is executed it will put its 
associated value on top of the parameter stack. 

Forth Note: If Forth were a strictly postfix language the syntax 
for integer would be: 

<value> < address of name string> integer 

The constant data for the circle area equation is defined as 
follows: 

314 integer pi*100 

The variable data could be defined as follows: 

1 integer smallradius 
7 integer mediumradius 
15 integer largeradius 
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When one of the above names is executed, it will push its 
associated data onto the stack: 

pi»100 . 31** 

small radius . 1 
mediumradius . 7 
largeradius . 15 

Forth Note: The following colon definition performs the same 
action as the integers above when executed: 

: mediumradius 7 I 

When mediumradius is executed, it will push a *7* onto the 
stack. The drawback of the colon definition is that the '7' is 
"hardcoded" into the definition. If mediumradius must put a 
different value on the stack, the definition would have to be 
recompiled . 

Integers, on the other hand, were designed so that their contents 
could be easily modified during program execution and thus are 
ideal for use as program variables. The operators used to alter 
the contents of integers are discussed below. 

Now let's make the circle area equation part of a Forth word 
which, when passed a radius value (expressed in meters) will 
return the corresponding area (expressed in centimeters squared) : 

: circlearea { nl - n.2 ) 

dup ( Make a copy of the radius. ) 

* ( Multiply: radius*radius , square it. ) 

pi*100 * ( Multiply the radius squared by the ) 

; ( pi*100 constant. ) 

smallradius circlearea . 31^ 
mediumradius circlearea . 15386 
largeradius circlearea . 70650 

Altering Integer Data 

The tForth words co , +to , on , and off are used to modify 
integer data: 

23 largeradius to ( Put a '23' in the largeradius integer. ) 
largeradius . 23 ( Get and display the contents of ) 

( largeradius . ) 

5 largeradius +to ( Add '5' to the contents of largeradius . ) 
largeradius . 28 ( Get and display the contents of ) 

( largeradius . ) 

largeradius off ( Put a 'false' flag, '0', in largeradius . ) 
largeradius . 

(cont. ) 
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largeradius on { Put a 'true' flag, '-l r , in largeradius 
large radius . -1 

to is used to change the contents of an integer to a specified 
value. +to is used to add a 4 byte value to the contents of an 
integer, off and on are boolean integer operators, usually 
used on integers which are being used as flags, off is used to 
turn an integer value 'off, i.e. to set the integer's value to 
'false 1 (0). on is used to turn an integer value 'on 1 , i.e. to 
set the integer's value to 'true' ('-1* or 'non-zero'). 

The Use of Integers Versus the Direct Alteration of Memory 

tForth's generic integer data structure (can be used to hold 
either constant or variable data) frees the programmer from 
having to treat variable data differently than constant data. 
They also free the programmer from having to remember the 'type' 
of a particular piece of memory. This is especially convenient 
in a multi-programmer programming environment where each 
programmer may not be intimately familiar with the constants and 
variables being used by another programmer. Any tForth 
programmer is able to get the value of any integer without having 
to know whether another programmer is using the integer as a 
constant or variable. 

A limitation of integers, however, is that they only support 
interaction with 4 byte data values. Handling of data sizes 
which are smaller (byte, word) or larger (arrays, data 
structures) than 4 bytes requires that the contents of memory be 
accessed directly. 

Directly Accessing the Contents of Memory 

The following words are the main words used for direct 
manipulation of data in memory. The stack notations for these 
words are: 

WORD PRON. STACK NOTATION 

! 'store' ( n a - | Stores the 4-byte value on 

the parameter stack, 'n' , into memory 
starting at the address 'a' . ) 

G 'fetch' ( a - n | Fetches the 4-byte value 'n* 

stored in memory starting at address 'a' 
and returns it on the parameter stack. ) 

w! 'w-store 1 ( w a - | Stores the lower 2 bytes of 

the 4-byte value on the parameter stack 
into memory starting at address 'a 1 . ) 
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w§ 



c! 



ce 



+ ! 



'w- fetch' ( a - w | Fetches the 2-byte value 'w 1 
stored in memory starting at address 'a' 
and returns it in the lower two bytes of 
the number on top of the parameter stack, 
the upper two bytes are set to zero. } 

' c-store' ( c a - | Stores the lowest order byte 
of the 4-byte value on top of the parameter 
stack into memory starting at address 'a'.) 

'c-fetch' ( a - c | Fetches the 1-byte value ' c' 
stored in memory at address 'a' and returns 
it in the least significant byte of the number 
on top of the parameter stack. The upper 
three bytes are set to zero. ) 

'plus-store' ( n a - | Adds the 4-byte increment 
value 'n f to the 4 -byte value located in 
memory starting at address 'a'. } 



Directly Altering Integer Data 

The execution of an integer variable name puts the value of the 
integer variable directly on the stack. To get the address of 
the location where an integer's data is stored, use the word 
addr ("adder") immediately after the name of the integer: 



hex 

largeradius addr 



478FE ( The contents of the integer ) 
{ largeradius are located in ) 
( starting at address '478FE' . ) 



To directly access the contents of largeradius , without using 
to or executing largeradius , the direct memory access words 
described above may be used to directly access the memory 
location ('479F6') where qty's contents are stored: 



12345678 479F6 ! 
479F6 £ . 12345678 

9876 479F6 w! 
479F6 v# . 9876 

FF 479F6 c! 
479F6 c@ . FF 



Store the 4 byte value '12345678' in ) 
memory starting at the address '479F6' . 
Fetch and display the 4 byte value ) 
residing in memory starting at address ) 
'479F6'. ) 

Store the 2 byte value '9876' in memory ) 
starting at the address '479F6'. ) 

Fetch and display the 2 byte value ) 
residing in memory starting at address ) 
'479F6'. ) 

Store the 1 byte value 'FF 1 into memory ) 
starting at the address '479F6'. ) 
Fetch and display the 1 byte value ) 
residing in memory starting at address ) 
'479F6'. ) 
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5 479F6 ! 
1 479F6 +! 
479F6 e . 6 



Store the 4 byte value ' 12345678 ' in ) 
memory starting at the address ' 479F6* . ) 
Add 1 to the k byte value located at ) 
address , '*79F6\ ) 

Fetch and display the 4 byte incremented ) 
result. ) 



Other Useful Direct Memory Access Operators 

and J , or! , not! , and xor! are memory operators which perform 
logical operations with data stored somewhere in memory. 

fill , move , and cmove are memory operators which perform memory 
operations on large sections of memory. See the "Memory 
Operators" section of the Glossary for more information of these 
words . 

Starting Forth Note 

Chapter 8 of Starting Forth discusses how the defining words 
variable and constant are used to create named variable 
locations and constant values in Forth. In tForth variable and 
constant have been replaced by the single word integer. The 
following table compares integers, variables, and constants: 



ACTION 

Create a 
named variable 
location: 



INTEGER 



VARIABLE/CONSTANT 



5 integer fred variable fred 



Store a value 
into a variable 



7 fred to 7 fred ! 



Fetch a value 
from a variable: 



fred 



fred @ 



Increment the 
contents of a 
variable : 



1 fred +to 



1 fred +! 



Get the address 
of a variable 
location: 



fred addr 



fred 



Create a 
named constant 
value : 



12 integer dozen 12 constant dozen 



Get the 

constant value: dozen dozen 

As the table shows, there is no substantial difference between 

- 33 - 



constant and integer when the purpose is the creation of 
constant data. The difference between integer and variable 
when creating variable data is that integer allows the creation 
of initialized variable data and the value of a variable created 
with integer can be obtained by simply executing the name of 
the integer variable. Variables created with variable must use 
the @ operator to obtain their values. If a program works 
mainly with 4 byte variables and never needs the addresses of the 
variable locations, the use of integer to create those 
variables can save many 'fetch' operations during the execution 
of a program. The integer operators to and +to are also 
more readable commands than the memory operators ! and +! 

Displaying the Contents of Memory 

The tForth utility word dump is used to display the contents of 
memory : 

479F6 10 dump 

479F6 FF 76 56 78 00 00 00 DA 8l 00 07 2F 83 63 6E 74 
.vVx / .cnt 

dump has the following stack notation: 

dump (an-) 

dump displays 'n' bytes of data starting at address 'a* in 
memory. The start address of the memory dump is shown on the far 
left of the display, dump displays memory in 16-byte chunks. 
Each byte in the memory dump is separated from the next byte by a 
space. The ASCII equivalents of the 16 byte values shown in the 
memory dump are listed on the far right side of the display. 
Here is how dump would be used to display 40 (hex) bytes of 
memory : 

479F6 40 dump 

479F6 FF 76 56 78 00 00 00 DA 8l 00 07 2F 83 63 6E 74 -Wx /.cnt 

47A06 07 37 89 63 75 72 72 65 6E 63 79 24 07 35 85 64 . 7 . currency$ . 5 . d 

47A16 61 74 65 24 07 30 88 64 65 63 69 73 69 6F 6E 07 ate$.0. decision. 

47A26 31 89 64 65 63 69 73 69 6F 6E 32 07 38 8C 6D 61 l.decision2.8.ma 
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PROGRAM CONTROL STRUCTURES 

There are four major types of program control structures: 

1. Conditional Execution 

Code within a conditional execution structure is 
executed only if certain conditions are met. 
The tForth words used for the implementation of 
conditional execution structures are: 

if else then 

2. Definite Loops 

Definite, or counted, loops are used to cause a set 
of instructions to be executed a specific number of times, 
The number of times the loop is to be executed is known 
prior to the start of the loop. The tForth words used 
for the implementation of definite loops are: 

do +loop loop i 

3. Indefinite Loops 

Indefinite loops are used to cause a set of instructions 
to be executed an unknown number of times. 
These types of loops are termed 'indefinite* because 
the number of times the loop will be executed is 
determined during execution of the loop. The tForth 
words used for the implementation of indefinite loops are: 

begin until again while 

k. Forced Execution 

Forced execution words are used when program execution 
must be unconditionally redirected to another section of 
the code. The tForth forced execution words are: 

abort abort* 1 exit leave 

A Special Note about tForth Program Control Structures 

In most Forth systems, program control structures can only be 
used within colon definitions. In tForth, program control 
structures can be used interactively. This is very useful for 
testing out ideas since the extra work required to create a new 
definition is eliminated and the dictionary doesn't become 
cluttered with test definitions. Several of the examples 
presented in the section are to be executed interactively. 
Interactive execution of a program control structure commences 
when the final word in the program control structure is entered 
(try the examples below) . 
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Conditional Execution 

The conditional execution structures allow programs to make 
decisions. In the following example, the word decision decides 
whether a 5 should be displayed by examining the flag passed to 
it: 



: decision { f 
if 

5 . 
then ; 

decision 

1 decision 5 



) ( Create a definition named decision . ) 
( Check the flag. ) 

{ IF it is true, non-zero, display a 5» ) 
( Mark the end of the 'if... then' structure. ) 

( is false so the 5 is n °t displayed. ) 
( 1 is true so the 5 is displayed. ) 



When the flag passed to if is true (non-zero) the code between 
the if and the then will be executed. When the flag is false 
(0) , if will reroute program execution to the code which 
immediately follows the then . 

The 'if... then' structure can be extended by inserting an else in 
the middle: 



: decision2 { 
if 

5 
else 

6 
then ; 

decision2 6 

1 decision2 5 



f - ) 



( IF the flag is true, display a five. . . ) 
( ELSE the flag is false, display a six. ) 



( Flag was false so a 6 was displayed. ) 
( Flag was true so a 5 was displayed. ) 



Definite Loops -- 'Do ... Loop' 

The following interactive example shows a 'do... loop' being used 
to display the numbers from through 9' 



10 



do 



loop 0123^5678 



Place the limit on the stack. ) 
Place the index on the stack. ) 
Start the loop. ) 
This is the code to be executed ) 
each time through the loop. ) 
9 ( End of the loop. ) 



Execution of a counted ' do . . . loop ' always requires the 
specification of the number of times the loop is to be executed. 
The count is specified by placing two numbers on the stack. 
These two numbers are referred to as the loop "limit" and the 
loop "index". The number of times the loop will be executed is 
determined by subtracting the index value from the limit value. 
So, in the above example, the loop will be executed 10 times. 

When the word do executes it moves the limit and index values 
from the parameter stack to the return stack. The index value 
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will be the top item on the return stack and the limit value will 
be the second item on the return stack, do is executed only once 
in a 'do... loop'. When the word loop executes it subtracts one 
from the index value on the return stack and compares the new 
index value to the limit value, loop is executed each time 
through the loop. When the index value equals the limit value, 
the loop is immediately terminated (this is why the limit value, 
10, was not displayed). 

The word i copies the top item on the return stack and places the 
copy on top of the parameter stack, i is normally used during 
execution of a 'do... loop' to get the value of the current loop 
index (which is the top item on the return stack during a 
'do. . .loop' ) . In the example, i was used to get the current loop 
count each time through the loop and . was used to take the 
number off of the parameter stack and display it. 

Note that the code in a definite loop will always be executed at 
least once since the loop termination check occurs at the end of 
the loop. 

Definite Loops -- 'Do ... +Loop' 

The 'do...+loop' definite loop structure is used when there is a 
need for a counted loop which "counts" by a value other than 
one. For example, to display the even numbers between and 10: 

10 2 do ( Pass the loop limit and index to do . 

i . ( Get the current index and display it. ) 

2 ( Place the loop increment value on the ) 

( stack for +loop . ) 
+loop 2 4 6 8 

The main difference between 'do... loop's and 'do. . . +loops' is 
that +loop is passed the desired increment value for the loop 
index. The number of times a *do...+loop' will execute is 
determined using the following equation (where square brackets 
indicate "integer part of"): 

[ (limit-index) /increment] = number of times loop will be executed 

So, the loop above was executed (10-2)/2 = 4 times. +loop also 
accepts negative increment values. When a negative increment 
value is used, the loop will not terminate until the index 
becomes less than the limit so the equation for calculating loop 
execution cycles becomes: 

[ (limit-index) /incremental = number of times loop will be executed 

10 20 do 
i . 
-2 
♦loop 20 18 16 Ik 12 10 
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A mistake such as will result in a seemingly infinite loop: 

10 do ( Start at '10' and count to '0'. ) 

i . 
3 
+loop 

The loop will eventually terminate. The initial loop index value 
'10' will be continually incremented by 3 until at some point, it 
gets so large that it will not be able to be expressed as a 
32-bit value. When the index. value reaches this 32-bit "cut-off" 
the value will appear to change from a very large postive number 
to a very large negative number. This large negative index value 
will continue to be incremented by 3 and eventually will reach 
zero. 

Indefinite Loops 

The most common indefinite loop structure is the 'begin. . .until' 
loop. In a 'begin. . .until' loop, the code between the begin 
and the until is executed until the flag passed to until is 
true (non-zero). If the flag passed to until is false (0), 
until will reroute program execution back to the code which 
immediately follows the begin. For example, the 'begin. . .until' 
loop below will not terminate until the user presses the 'a' 
key. The example uses the word key , which has not yet been 
discussed, to obtain the user's input and to place the ASCII 
value of the character pressed on the parameter stack. Since the 
ASCII value for 'a' is 97, a comparison is made to determine 
whether the key pressed was the 'a' key: 

decimal 
begin 

key 97 = 
until 

After this example is entered the text will remain highlighted 
UNTIL the lowercase 'a' key is pressed. 

Placing Conditionally Executed Code in an Indefinite Loop 

while is a conditional-test word which may be included in any 
indefinite looping structure, while allows code which is to be 
conditionally executed to be included in an indefinite loop. If 
the flag passed to while is true (non-zero) , the code following 
the while will be executed. If the flag passed to while is 
false (0) , then the code after the nearest following while , 
again , or loop will be executed, again always reroutes 
program execution back up to the code which immediately follows 
the begin 

To use the example below, send the underlined text to tForth and 
then press the 'a* key six times. Each time the 'a' key is 
pressed (after the 1 a' key is pressed) the current index value 
will be displayed and incremented. Press any other key to 
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terminate the loop: 



decimal 

integer index 



begin 



while 



key 97 = 



index 

1 index *to 



again 12 3^5 



change to base 10 ) 

Define an integer variable to be ) 

used to hold an index value. ) 

Start the loop. ) 

Did the user press the 'a' key ? ) 

WHILE the user did press the 'a* ) 

key execute the following code. ) 

Display the current index value. ) 

Increment the index by one ) 

and go back to the top of the loop. 



Any number of while decision points may be inserted into an 
indefinite looping structure. 

Forced Execution 

The forced execution words will immediately and unconditionally 
redirect program execution when they are executed. 

The Word leave 

leave is a forced execution word used to immediately leave from 
any definite or indefinite looping structure. When used inside 
of a definite looping structure, leave is responsible for 
removing the loop limit and index from the return stack: 

Note: A "nested" program control structure is a control 
structure which contains another program control structure. The 
leave example below uses nested control structures; an 
'if... then' structure is used inside of a 'do... loop' structure. 
A control structure may contain any number of nested control 
structures. However, words which leave control structures { 
leave and while ) will only leave from the current control 
structure to the next outer control structure. 



shortened- loop 
10 do 



i 7 > 
if 

leave 
then 



- ) 
We seem to want to run the loop ) 
10 times. ) 

Print the current index value. ) 
Is the loop index greater than 7 
If it is. . . ) 
leave this loop. ) 



loop 



shortened- loop 012345678 

leave will always reroute program execution to a point right 
outside of the nearest following until , again , loop , 
or +loop . If leave is used inside a set of nested looping 
structures, it will only leave the current loop. 
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The Word Exit 

exit is a forced execution word which must be used within a colon 
definition. Whenever exit is encountered in a colon definition 
it will immediately terminate execution of that colon definition 
and will redirect program execution back to the word which 
originally called the definition: 



unfinished ( 
1 

2 . 

3 • 
exit 

4 . 



unfinished 12 3 



Display a ' 1 ' . ) 

Display a '2'. ) 

Display a ' 3 ' • ) 

Terminate execution of this definition. ) 

The '4* will not be displayed. ) 

The '5* will not be displayed. ) 



As soon as the exit in unfinished was reached, execution of 
unfinished was terminated. 

The Words abort and abort" 

abort will cause a Forth system abort. In a Forth system abort 
the return stack and parameter stack are cleared and Forth is 
restarted, abort may be used interactively or within a colon 

definition. 

abort" is a version of abort which accepts a flag and, if the 
flag is true (non-zero), aborts, issues a beep, and displays an 
error message on the "explain" screen ([USE FRONT] [EXPLAIN] ) . 
The error message for abort" immediately follows abort" and is 
terminated with a trailing quote. Note that there must be at 
least one space or tab between abort" and the start of the error 
message, abort" may only be used within a colon definition: 

: tes tabor t ( f - ) 

abort" Error Error" ; 

testabort ( Nothing should happen. ) 

1 testabort ( The system should beep and the ) 

( error message "Error Error" should ) 
( be displayed on the explain screen. } 
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CHARACTER AND STRING I/O 

Character input 

ascii 

ascii is a character manipulation word which returns the ascii 
value of the single character which follows it: 

ascii s . 115 ( The ASCII code for an f s' is decimal 115. ) 
115 . 115 { This is another way to put the ASCII code ) 

( for an 's' on the stack. ) 

Note that 'ascii s' has the same effect as '115' t both command 
sequences place the decimal ASCII value for ' s' on the stack. 
The '115' is a more meaningful result when it is viewed as the 
result of ascii 

ascii can be use to make all single character comparisons in 
your program much more readable: 

115 116 = . ( Comparing the ASCII codes for 1 s 1 and 't f ) 

( in an unreadable fashion. ) 

ascii s ascii t = . ( Does the ASCII code for ' s' equal the ) 

( ASCII code for 't» ? The false [0] flag ) 
( returned shows that they are not equal. ) 

?t 

?t is a character input word which checks to see if any 
characters input by the user are available. If the user has 
typed a character, a true (non-zero) flag will be returned. If 
no user input characters are waiting, a false (0) flag will be 
returned. The word keypress below spins in a loop, printing a 
message, until the user presses any key: 

: keypress ( - | Displays a message until any key is pressed. ) 
begin 

cr 

. " Press any key to terminate . " 
?t 

until 
cr ." Done." ; 

keypress 

Press any key to terminate. 

Press any key to terminate. 

Done. 
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The Word key 

While ?t only reports on the presence of user input, key is a 
character input word which waits until the user presses a key and 
then returns the ASCII code for the key pressed, key forces the 
system to wait until the user inputs a character, key will be 
incorporated into the keypress example to obtain a more specific 
response from the user. In the new example, the user must press 
a certain key, an 's', to terminate the message printing loop, 
but can press any other key to print the message out: 

: keypress ( - | Displays a message whenever any key except an 
's* is pressed. When an *s' is pressed, the loop terminates. ) 
begin 

cr ( Print a carriage return followed ) 

{ by the message. ) 
. " Press an 's' to stop or any other key to continue." 
key ascii s - { Did the user press the 's 1 key ? ) 
until 
cr . " Stop." ; redefining keypress 

keypress 

Press an 's* to stop or any other key to continue. 
Press an 's 1 to stop or any other key to continue. 
Stop. 

Note that when this new version of keypress was sent to tForth, a 
"redefining keypress" message was issued. 

Character Output 

emit takes a number and outputs the corresponding ASCII 
character. All of the other character output words are built 
using emit . cr uses emit to output a carriage return and a 
linefeed, space uses emit to output a space. The following 
demonstration uses cr twice to produce two carriage returns, 
uses space twice to produce two spaces, and uses emit three 
times to output three asterisks: 

: demo ( - ) 
cr cr 
space space 
42 emit 42 emit 42 emit ; 

demo 

«** 

emit is a vectored output routine. When emit executes it checks 
the state of four output device flags. There is a flag for the 
screen (crt) , the printer (lp) , the editor (edde) , and the 
modem/serial port (ser). If a flag is set, it means that the 
corresponding output device is currently enabled. Whenever 
emit is used, it must output the character to all output devices 
which are currently enabled. Since emit is smart enough to 
know how to talk to all of the devices mentioned above, the 
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programmer does not have to worry about the idiosyncracies of 
each device. 

String Creation 

The string manipulation word " ('quote') will construct 
either a temporary or permanent string in memory and will return 
the address and length of the string on the stack: 

" This is a test." . . 31 ^71930 

" will place all characters between itself and the trailing 
quote into the string being constructed. Because " is a 
Forth word, it must be surrounded on both sides by at least one 
space or tab. The text to be included in the string should 
immediately follow the " and the space. The text should be 
terminated with a closing quote. The closing double quote is 
used only as a delimiter, so it does not have to be separated 
from the rest of the text. Double quotes may not be used within 
the string text. 

String Output 

type is a string output word which, when passed the address and 
length of a string, will output the string to the screen (and/or 
any other current devices) . 

" This is a string." .s type 746BD 25 This is a string. 

.s was used in the above example, between the string 
construction and type , to show that " does leave the address 
and length of the string on the stack for type . type was then 
used to output the string to the screen. 

String Integers 

string is the string-handling equivalent to integer . In the 
following example the text within the quotes is the string data, 
mystring is the name assigned to the string data, string 
makes mystring an executable word which will put the address 
and length of its associated string data on the stack when 
executed . 

This is how string is used: 

" This is string data." string mystring 
This is how the mystring string may be displayed: 

mystring typeThis is string data. 
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An empty string is created when no characters are included 
between the quotes (when quote-space-quote is used) : 

" " string emptystring 

Changing String Data 

The word "to is used to alter string data. The use of "to is 
similar to the use of the integer manipulation word to . "to 
is smart enough to handle changing string sizes. 

" " string stringinteger ( Create an empty string integer. ) 

" abcdefg" stringinteger "to { Store some text in the string } 

( integer. ) 

stringinteger type abcdefg ( Display the contents of the ) 

( string integer. ) 

String Input 

The tForth word query takes string input from the editor 
environment and passes the input to tForth. When query is 
executed, it waits until it is passed a string from the editor. 
Any string may be passed from the editor to query by selecting 
the desired string and pressing [ANSWER] while holding the 
[USE FRONT] key down. 

This is the stack notation for query : 

query (-an) 

query returns on the stack the address 'a' and length , n* of the 
string passed to it. 

In the example below, query is used to obtain a line of user 
input. The address and length of the user's input, returned by 
query , are passed on to type so that the input will be 
immediately displayed. To use the example below perform the 
following steps: 

o Send the word stringinput to tForth. 

o Enter the text you would like to return to query 
In the example, 2 spaces were typed, followed by 
the words "Hello there.", followed by 2 more spaces. 
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o Highlight your text and return the text to query with 
the use of [USE FRONT] [ANSWER] . 

: stringinput ( - ) 

space ( Put a space in front of the response string. ) 
query ( Wait for string input. ) 
type ( Display the input string. ) 



stringinput Hello there. Hello there. 

The first instance of " Hello there. " above was typed in 
response to query . The second instance of M Hello there. " 
was output by stringinput . 
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NUMERIC I/O AND NUMBER FORMATTING 

Numeric input involves the conversion of ASCII strings which 
represent numbers to numbers which may be placed on the parameter 
stack. Numeric output involves the conversion of numbers to 
strings of ASCII characters which may be displayed using the 
string I/O words. There are four categories of numeric I/O 
words: words used to control the numeric conversion base, words 
used to handle numeric input conversion, words used to handle 
formatted numeric output, and words used to handle standard 
numeric output. 

Numeric Conversion Base 

Numbers are always converted with respect to the current numeric 
base. The current number base is controlled by the system 
integer base . The two most commonly used number bases, base 
ten (decimal) and base 16 (hexadecimal), may be chosen with the 
special words decimal and hex : 

( The system was in hexadecimal base when these definitions 
were defined. ) 



decimal ( 



) Oa base to 



hex ( 



) 10 base to 



The examples below demonstrate how you may set or change the 
current numeric base: 



decimal 






10 


15 


20 




hex 






.s 


A F 14 




2 


base 


to 




.s 


1010 


1111 


10100 ( 


7 


base 


to 




.s 


13 2J 


L 26 




decimal 






. 


. 


20 15 


10 ( 



Set the base to decimal. ) 

Put some numbers on the stack. ) 

Change the base to hexadecimal. ) 
Display the hexadecimal equivalents ) 
of the numbers. ) 

Change base to base 2, binary. ) 
Display the binary equivalents ) 
of the numbers. ) 

Non-standard bases are also allowed. ) 
Display the base 7 equivalents. ) 

Change the base back to decimal ) 

and remove the numbers from the stack. ) 



Note that both the number input words and the number display 
words are affected by the current base setting. 
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Numeric Input Conversion 

The word number takes the address and length of a string, the 
desired conversion base, and tries to convert the string to a 
number: 

decimal 

" 1234 M 10 number . . -1 123*1 

" 123X4" 10 number . 

In the examples above, " was used to create a temporary string. 
The address and length of the temporary string, and a '10' for 
base 10 were passed to number. The '10' was treated as a decimal 
'10' since decimal was used above to set the system base to 
decimal . 

In the first use of number the temporary string contained a 
sequence of valid ASCII numerical characters, number was able to 
successfully convert the string to a number and returned two 
values, a true (non-zero) flag and the converted numerical value, 
on the parameter stack. 

In the second use of number the temporary string contained an 
invalid numerical character {the 'X'). number was not able to 
convert the string to a number and returned only one result, a 
false (0) flag, on the stack. 

Number Output Conversion and Number Formatting 

The number formatting words are used to convert binary numbers to 
printable strings of ASCII numerals. 128 bytes of a 384-byte 
scratch area called 'the pad' {see diagram on the following page) 
are used by the number formatting words to hold the output string 
as it is being constructed. Executing the word pad will cause 
the address of a location 128 bytes into the pad to be placed on 
the parameter stack. An integer named hid is used to hold a 
pointer to the spot in the string where the next character will 
be inserted. 
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Number Formatting 

(decimal) 



384 bytes 



128 bytes 



3 4 



tt 



pad 



hid 



These are the names and functions of the number formatting words 
to be used in the example: 

<# ( n - n ) 
( 'less-sharp' ) 

Must always be used at the start of a number 
conversion process. Initializes the hid pointer with 
the address of pad (the number to be converted, 'n' , 
should be on the stack, although <# does not use it) : 

:<#(-) pad hid to ; 

hold ( c - ) 

Lower level word used by # . Decrements the hid 
pointer by one and then takes the ascii value from the 
stack and places it in the next available spot in 
the string: 



hold { c 


" ) 


-1 hid 


+ to 


hid c! 


• 



{ Decrement the hid pointer. ) 
( Store ASCII value into string. ) 

digit ( nl n2 - nl» c ) 

Lower level word used by # . Extracts one digit from 
the number being converted 'nl' using the specified base 
'n2' and converts the digit to its corresponding ASCII 
value. Returns the remainder of the number 'nl 1 ' and the 
ASCII value 'c' . 

# { n - n' } 
( ' sharp ' ) 

Uses digit to extract one digit from the number on top of 
the stack {the number being converted) and then uses 
hold to] insert the ASCII code for the digit into string 
being constructed in the pad: 

: # ( n - n' ) base digit hold ; 

#> ( nl - a n2 ) 
{ ' sharp-greater' ) 

Removes the remainder of the number being converted from 
the stack (the number should be zero if it was completely 
converted), and returns the address 'a' and length 'n2' of 
the output string: 

: #> ( nl - a n2 ) 



drop 
hid 
pad 
over 



Drop the remainder. ) 
Put string start address on stack. ) 
Put end address of string on stack. 
Put copy of start address on top. ) 
Subtract to get string length. ) 



The simple example below shows how number formatting words could 
be used to convert a 3~digit number to a string: 
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234 <#####> space type 234 

The diagram of the pad showed how the example string above 
looked while it was under construction. When the diagram was 
drawn, only 2 of the 3 digits had been added to the string. Note 
that the string is constructed from right to left. The least 
significant digits are inserted into the string first, and the 
most significant digits last. The hid pointer is always 
pointing to the current last character in the string. 

u. 

The word u. , which is used to display unsigned numeric 
values, solves the example task in a more generic manner: 

: u. ( n - ) 

<# #s #> «3pace type ; 

hex 

FFFFFF34 u. FFFFFF34 

u. uses #s , an extended version of the # formatting word, 
to extract all the digits from any size number: 

#s ( n - ) 
( ' sharp-s' ) 

Continually extracts digits from the number 
being converted and inserts the ASCII values 
into the string being constructed until the 
number being converted is reduced to zero: 

: #s ( n - ) 

begin 

# { Get one digit at a time. ) 

dup ( Copy the remaining value. ) 

0= ( Is it zero yet ? ) 

until ; ( Go until the number is 0. ) 

Dot (.) 

The word . , which is used to display unsigned or signed 
numerical values , uses the number formatting word sign : 

sign ( n - ) 

If the number on the stack is negative sign 
will insert a minus sign (ASCII value = hex 2D) 
into the string being constructed in the pad: 

: sign ( n - ) 

0< ( Is *n f negative ? ) 
if 

2D hold { If it is, insert a '-'. ) 
then ; 

(cont. ) 
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( n - 

dup 

abs 

<# 
#s 

swap 
sign 

#> 

space 

type ; 



) 



) 



Duplicate number to convert. 

Take absolute value of copy. 

Start number formatting. ) 

Convert all of the digits. ) 
( Put original number on top. ) 
( If negative, insert *-* in string. ) 
{ End conversion. ) 

( Display string. ) 



hex 

FFFFFF34 



-CC 



Note that . , which is affected by the sign bit on a number, 
displayed the value ' FFFFFF3V in a different manner than u. 
did previously. 

Inserting Special Characters Into a Formatted String 

The following example shows how number formatting can be used to 
convert a 6-digit number to a common date format (mm/dd/yy) : 

Note: It is customary, but not necessary, to use a '$' at the 
end of string names and string-handling word names. For 
example, date$ is a word which creates and displays formatted 
date strings. 

: date$ ( n - | Takes 6-digit number, converts it to mm/dd/yy 
date format string, and displays string. ) 



# 
# 
ascii 

# 

ascii 

# 
#> 

space 
type ; 



( Start the number conversion process . ) 

{ Convert least significant digit of year. ) 

( Convert most significant digit of year. ) 

hold ( Insert a '/' in the string. ) 

( Convert least significant digit of day. ) 
( Convert most significant digit of day. ) 

hold { Insert a '/' in the string. ) 

( Convert least significant digit of month. ) 
( Convert most significant digit of month. ) 
( End conversion process. ) 

( Display date string. ) 



100961 date$ 10/09/61 

The date string is constructed from right to left. Note that the 
phrase 'ascii / hold' was used in place of the equivalent 
phrase '92 hold 1 for readability. 

Storing Formatted Strings in String Variables 

The following example shows how a value with any number of digits 
can be converted to the United States currency format 
(Sdddd.cc). A string variable is created for use as a storage 
for the currency string which can be printed out at a later time: 



- 51 - 



Note: Since the pad is used as a scratch area by many tForth 
words, important data, such as formatted strings, should not be 
kept in the pad. 

" " string currency$ ( Create an empty string variable location, ) 

: makecurrency { n - | Converts a number to Sdddd.cc format 
string and saves string away in string variable. ) 

<# { Start number formatting process. ) 

# ( Convert least significant 'cents' digit. ) 

# { Convert most significant 'cents' digit. ) 
ascii . hold ( Insert decimal point. ) 

#s ( Insert all of the 'dollars* digits. ) 

ascii $ hold ( Insert dollar sign. ) 
#> ( End number formatting process. ) 

currency$ "to ( Copy string into variable ) 
; ( for later use. ) 

1257595 makecurrency 

currency$ space type $12575.95 

The string creating word string and the string operating word "to 
were discussed in the section on string I/O. 

. r and u . r 



.r and u.r are formatted versions of the words . and u. 
These words print signed and unsigned values, right justified, in 
a field with a specified width: 



fixedfont 



: signed-aligned 
cr 
123 10 .r 

123^56 10 

FFFFFF34 10 



{ For these words to print with proper ) 

{ alignment in the editor, a non-proportional 

( or fixed, font must be used. ) 

( - ) 

( Output a carriage return. ) 
cr { Print 123 in 10 char field ) 
.r cr ( followed by carriage return. ) 
.r cr ; ( Repeat for 2 other numbers. ) 



signed-aligned 
123 
123456 
-CC 



: unsigned- aligned 
cr 
123 20 

123456 20 
FFFFFF34 20 
unsigned-aligned 

123 
123456 
FFFFFF34 
variablefont 



- ) 

{ Output a carriage return. ) 
u.r cr ( Print 123 in 20 char field ) 
u.r cr ( followed by carriage return ) 
u.r cr ; ( repeat for 2 other numbers 



{ To return to a proportional 
( font, if you'd like. ) 
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LOCAL VARIABLES 

A major drawback of the Forth parameter stack is that with 
several parameters on the stack, the manipulations required to 
get at a certain parameter become cumbersome and the resulting 
code unreadable. For example, this is a routine which sums the 
numbers between and n where n is an arbitrary limit. In this 
routine, the arbitrary limit is reached when the user hits a key: 

: summation ( -> n | Spins in a loop, summing the loop count, 
until the user hits a key. Returns the summation on the stack. ) 






begin 



1+ 

dup 

rot 



swap 



?t 
until 

drop 



The initial sum is 0. ) 

The initial loopcount is 0.) 

Start the loop. ) 

Increment the loop count. ) 

Copy the loop count. ) 

Rotate the current sum to the top of ) 

the stack. ) 

Add the copy of the loop count to the } 

current sum. ) 

Put the loop count back on top. ) 

Has the user pressed a key ? ) 

Go until ?t reports that the ) 

user has pressed a key. ) 

Drop the loop count but leave the ) 

summation on the stack. ) 



summation . 4367^90 

The inner loop of the above routine, the words between the 
begin and until (two program control structures which will be 
explained later) , is very difficult to comprehend at first 
glance. The stack notation indicates that the routine takes no 
inputs and returns one output but it does not provide any 
information regarding the use of the stack within the routine. 
Even though this example has only a maximum of three items on the 
stack, it is very difficult to work through without resorting to 
pencil and paper to keep track of the stack usage. 

A Description of tForth's Local Variables 

In tForth programmers are allowed to create 'local variables', 
that is, variables which are valid only during execution of the 
word in which they are defined. The main advantage of local 
variables is that they help produce more readable code by 
eliminating confusing stack manipulations. 

This is how local variables are used in a definition: 
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<name> ( - ) 

local nl 
local n2 



local ni 



The word local is used to create and name a local variable. The 
local variable is not initialized to any value. Any number of 
local variables may be created in a definition. Since the 
variable is a local variable, references to <name>'s local 
variables are only valid within <name> None of the words which 
call <name> and none of the words which <name> calls can 
reference <name>'s local variables. 

The next example shows the summation routine after it has been 
rewritten to take advantage of local variables: 

: summation ( -> n | Spins in a loop, summing the loop count, 
until the user hits a key. Returns the summation on the stack. ) 

local sum ( Creating and naming a local variable. ) 
sum to ( Initializing sum with a zero. ) 

begin 

1 sum +to { Increment the contents of sum by one. ) 
?t 

until ( Go until keypress. ) 

sum ( Leave the result on the stack. ) 



The use of a local variable makes this version of summation 
much easier to read and understand. 

Local Variable Operators 

The two integer operators to and +to are used to change and add 
to the contents of local variables. The use of these two 
operators is demonstrated in the example above. 



- 54 - 



THE tFORTH TECHNICAL REFERENCE MANUAL 



INTRODUCTION 

The tFORTH Technical Reference Manual contains 
implementation- specific information about the tFORTH FORTH 
implementation. The following topics are covered: 

* SYSTEM MEMORY USAGE 

Includes a ROM/RAM memory map of the entire system 
and a close-up memory map of the tFORTH RAM 
execution area. 

* DICTIONARY STRUCTURE 

Detailed memory maps showing the layout of the tFORTH 
dictionary header and dictionary code areas. 

* VOCABULARY STRUCTURE 

The search order and the active array, open and closed 
vocabularies , creating/ removing vocabularies and the 
extant array. 



* 



* 



* 



* 



"RUNNING" tFORTH 

How interpret works. 

COMPILATION 

Structure of a dictionary header and code entry. 

Token threading versus address threading. 

EXECUTION OF TOKEN THREADED CODE 

Names of the various pointers and register usage 

Nested execution levels. 

IMPLEMENTATION OF INTEGERS 

The ' iv' pointer and integer tables. 

System integers. 

IMPLEMENTATION OF LOCAL VARIABLES 

How local variables are compiled and executed. 

IMPLEMENTATION OF PROGRAM CONTROL STRUCTURES 
How program control structures are compiled and 
how they are interactively executed. 
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SYSTEM MEMORY USAGE 

The System Memory Map on the following page gives a general 
overview of the memory layout of the ' V777' system, including 
ROM/RAM memory specifications. A second memory map, shown a 
couple of pages later, contains a close-up memory map of the 
tFORTH RAM area and lists the tFORTH words commonly used to 
traverse memory. 

ROM 

128K of ROM is located starting at address $00000. The lowest IK 
bytes in the ROM are used to hold the system reset exception 
vector and the rest of the 68000 exception vector table 
(exception handling and interrupt handling routines are discussed 
later). The ROM'ed tFORTH and 'V777* editor code fill up the 
rest of the low memory ROM space. 

RAM 

The 'V777' system has 256K to 512K bytes of RAM located starting 
at address $400000. tFORTH uses half of the RAM area (128K 
bytes) for its alterable vocabularies and other dynamic data 
areas. The remaining 128K bytes of RAM are used by the editor. 
The boundary between these two areas is alterable. 
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System Memory Map 

Addresses in hexadecimal 




440000 



Last RAM location 



420000-43FFFF Editor RAM 



4108A0-41FFFF tFORTH* dictionary 

40EC00-41089F Token table 
40A280-40EBFF Variable area 

400000-40A27F Display memory 



1 00000-1 5FFFF Spelling Checker ROM 



040000-043FFF User Dictionary RAM 

000400-01 FFFF tFORTH' editor code 
000000-0003FF 68000 Exception Vector Table 



ROM 



RAM 



The tForth RAM Memory Map 

The following page contains a close-up view of the tFORTH RAM 
area. 

Display Memory 

The first 28K bytes of the tFORTH RAM area is used for display 
memory. The V777 screen has 672 pixels horizontally and 3^4 
pixels vertically. rams tart will return the address of the 
start of the screen display memory when executed. The first byte 
in the display memory area corresponds to the 8 pixels on the far 
left of the top line on the screen. 

Variable Memory 

Following the display memory is the 4-5K area used for array 
variables and for the return and parameter stacks. spO will 
return the address of the base of the parameter stack when 
executed. sp@ returns the address of the top of the parameter 
stack when executed. 

Token Table 

The address of the start of the 2K byte token table is obtained 
by asking for the address of the first token in the table: 

hex 

+ table . 40EC00 

The token table contains an ordered list of the addresses of most 
of the words in the system. The layout and use of the token 
table are explained in the section covering the tFORTH compiler. 

The rest of tFORTH* s RAM allotment is used by the dictionary. 
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top 



applic 



'tFORTH* 
dictionary 



here 



\ origin, 



+table. 



spO. 



ram start 



tForth memory Map (RAM) 



Addresses in hexadecimal 




*fUTHMEH0PtowWfc*itf »n 



W; 



'l II ■■•■■| ■•■•■• r - ., ■, 



USER vocabulary headers 



Available dictionary space 
( applic here - ) 



USER vocabulary code 




41FFFF 



Last 1FORTH' location 



4108AA-41FFFF 1FORTH' dictionary 

4OEC00-41089F Token table 

Return stack 
Subroutine stack 

40A280-40EBFF Variable area 



400000-40A27F Display memory 



Dictionary 

origin will return the address of the start of the tForth 
dictionary space when executed, top returns the address of the 
first byte BEYOND the end of the tForth dictionary space. 

Initially, the tForth dictionary contains three vocabularies of 
words. The approximate locations of the header and code areas 
(explained later) for each of the three vocabularies are shown in 
the diagram. The tForth word here is used to return the address 
of the next available byte location in the code area of the 
current 'open' vocabulary, applic will return the address of the 
next available byte in the header area of the current 'open' 
vocabulary (+1). The following calculation is used to determine 
the amount of remaining tForth dictionary space: 

hex 

applic here - . 186C9 ok 
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THE tFORTH DICTIONARY STRUCTURE 

As the previous memory map illustrates, the tForth dictionary 
space contains two types of data areas: the 'header* area and 
the 'code' area. The header area is where the header portions of 
all words in a vocabulary are stored. The code area is where the 
code portion of all words in a vocabulary is stored. Each 
vocabulary is given its own header and code area. 

The Dictionary Header Area 

The diagram on the following page contains a close-up view of an 
dictionary header area. The first four bytes in a dictionary 
header area contain a 32 -bit value which indicates how many bytes 
of individual header entries this header area currently contains . 

The first header entry in every vocabulary belongs to an 
invisible word used to mark the start of the individual 
dictionary header entries. This 'stub' word is 1 character in 
length with a name of 'null' . The ASCII code for the null 
character is 00. The entry for the stub word is not a complete 
dictionary header, it contains only the length byte and the 
single character in the name. 

The last header entry in every vocabulary belongs to another 
invisible word named 'del' (ASCII code = hexadecimal fF) . 'del' 
is used to mark the end of the dictionary header entries. The 
'del' entry is a complete header entry. The encoded token value 
used in the 'del' header entry is the highest possible encoded 
token entry. 
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'0 



* „ * / w encode^ jtokea vanish , s 



length byte 



char 



char 



char 



(up to 32 characters) 




2 bytes 



Structure of a Dictionary Header 



Adding Entries to the Header Area 

The dictionary header area grows downward in memory. Any new 
entries added to this vocabulary area will be placed between the 
'mil' and 'del' header entries (the 'del' header entry is moved 
to a lower memory location to accommodate the new entry) . 

Structure of an Individual Dictionary Header Entry 

The structure of a tForth dictionary header entry is shown in the 
diagram on the following page. The first two bytes in the header 
entry contain an encoded version of the token value assigned to 
the word. The third byte in the header structure is a length 
byte. The bytes following the length byte contain the ASCII 
codes for the characters which make up the word's name. 
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Header entry 
which marks the 
end of the 
dictionary header 
entries for this 
vocabulary. 



8 



1 



7 



I ~ — ""**! 

rJpBp mwmfm 



jffiwgHw nmjj.nu wwwwtwTnwwtttw 




Higher Memory 

Character in name 
(name is 'del'). 



Highest possible encoded 
token value. 



Length byte with high bit set 
(length = 1). 



(header structures for words in this vocabulary) 



Partial header entry 
which marks the 
start of the header 
structures. 



Number of bytes 
in the Header Area 
(4 byte value). 



\ 



' i V i 'vi Vn'i" i ' ii h i r 



> , <Ss, v . >'t X / S 

\/» ^ 



* s _^T ■• 






8 ! 1 






] 



Length byte with high bit set 
(length = 1). 



Character in name 
(name is 'nul'). 



Lower Memory 



2 bytes 



Close-Up of the Dictionary Header Area 



The diagram on the following page gives a close-up view of the 
length byte in a header entry. Bit 7 is used during dictionary 
searches, bit 6 is used to mark IMMEDIATE words, and bit 5 is 
reserved for future use. Bits 4 through are used to record the 
length of the word's name. Since only 5 bits in the length byte 
are available for recording the length of a word's name, only the 
first 32 characters in a word's name are significant. 
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I&1 


' 6;; ; : 


■■B,\ 


4' 


: H 3-^ 


\$\: 


l^j/i 


-.0. 



4 N - 



Bits used to record 
name length 



Reserved 
IMMEDIATE Bit 



Dictionary Search Bit 
(always set) 



Structure of the Length Byte 



The Dictionary Code Area 

The following diagram shows a close-up of the dictionary code 
area. 10 bytes of data are located at the start of every tForth 
code area. The first two bytes contain an 68000 assembly 
language * JMP (A3) ' instruction. The next byte is the actual 
token for the VOCAB defining word. The byte is a flag which 
indicates whether the code space contains an odd or even number 
of bytes of code. The next two bytes contain the tier and token 
information for the vocabulary to which this code area belongs. 
The final four bytes of this 10 byte data structure are used to 
hold a 32-bit value which indicates how many bytes of code this 
code area currently contains. 

Adding Code to the Code Area 

As new definitions are added to the system, the code portions of 
the new words which belong to this vocabulary will be placed in 
successive memory locations in the code area. The code area size 
field will be incremented accordingly as code is added. The code 
area grows toward higher memory locations. The odd size flag 
will be set whenever the vocabulary is closed if the vocabulary 
contains an odd number of code bytes . The words which reopen a 
vocabulary will check a vocabulary's odd size flag whenever the 
vocabulary is opened. 
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Number of bytes of code 

in this vocabulary's code area 

(4 byte value) 



Tier token 
for this vocabulary 



VOCAB token 



Token for 
this vocabulary. 



Odd Size Flag 



J MP (A3) 



2 bytes 



Higher Memory 



Lower Memory 



Close-Up of the Dictionary Code Area 



VOCABULARIES 

The words in a FORTH dictionary are usually subdivided into 
several smaller groups of words called 'vocabularies'. The 500 
or so words in the tForth dictionary are located in four 
different vocabularies: 

forth vocabulary Contains all of the 'standard' FORTH 

FORTH words supported by tForth 
and all tForth FORTH extension words. 
These words are located in ROM and 
may not be altered (the token table 
may be 'patched 1 to point to a new RAM 
definition of a ROM word if necessary) 

user vocabulary The user vocabulary is used to hold 

the user's definitions. 

arithmetic Contains the code which corresponds to 

vocabulary the user's calculations in the text. 

function vocabulary Contains the code which corresponds to 

the functions to be used in calculations 

in the text. 

There is also an invisible vocabulary which is used to hide all 
of the editor words . 

Vocabularies help arrange the words in the dictionary into 
smaller groups of related words. During compilation, the 
programmer can help the compiler by specifying in which of the 
vocabulary subsets of words the next word, or group of words to 
be compiled, is located. This can speed up the compilation 
process since the compiler performs less time searching the 
dictionary. How to specify a 'vocabulary search order' is 
discussed next. 

The Vocabulary Search Order 

The vocabulary search order determines which of the available 
vocabularies in the system are searched whenever the compiler or 
interpreter need to find a word. A list of the vocabularies 
contained in the current search order is kept in an array named 
'active' . 

The Word active 

active is a tForth word which returns the address of the start of 
the active array when executed. The active array is 32 bytes in 
length. The first entry in the active array contains the token 
corresponding to the vocabulary which is first in the search 
order. The second entry in the active array contains the token 
corresponding to the second vocabulary in the search order, and 
so on. Up to 16 vocabularies may be included in the search order 
list at one time. The active array is traversed by find until 
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either 16 vocabularies are searched or until a word-length 
(16-bit) value (hexadecimal FFFF) is encountered. 

Specifying the Search Order 

A vocabulary may be placed first in the search order by executing 
its name. If the vocabulary was already included in the search 
order, its token will be moved from its current position in the 
active array to the first spot in the array and the rest of the 
array will be adjusted to close the gap. If the vocabulary is 
new to the search order its token will be inserted at the start 
of the array. 

Adding New Words to a Vocabulary 

New definitions may only be added to the vocabulary which is 
currently 'open' . In the tForth RAM Memory Map diagram the 
user vocabulary is the current open vocabulary. When a 
vocabulary is 'open' there is a memory gap between the top of the 
vocabulary's code area and the bottom of the vocabulary's header 
area. When new definitions are added to the open vocabulary, the 
memory required for the new definition's code and header is taken 
from the 'open' pool of memory. 

The Word add to 

The tForth word addto is used to open a vocabulary: 

add to <name> 

Only one vocabulary may be open at once, addto will close the 
current open vocabulary before it opens the vocabulary specified 
by <name> . 

The diagram on the following page shows how the vocabulary 
closing and opening process works. A vocabulary is closed by 
closing the gap between the vocabulary's header and code areas in 
memory. A vocabulary is opened by creating a gap between its 
code and header areas. 

Creating New Vocabularies 

The Forth-83 defining word VOCABULARY is used to add new 
vocabularies to the system. The following actions are used to 
add a new vocabulary: 

1. The new vocabulary's header and code are placed in the 
header and code areas of the currently open vocabulary 
(the new vocabulary's parent vocabulary). 

2. The contents of memory between ' applic' and 'top-l* are 
shifted downwards by 20 bytes to make room for the 10 
bytes of data stored at the start of every dictionary 
header area and for the 10 bytes of data stored at the 
start of every dictionary code area. (cont.) 
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Opening and Closing Vocabularies 



top 




MtfTRMETIC . headers 



"ARITHMETIC: -cod* 



applic 



here 



origin 



USER headers 



Available 

dictionary space 

( applic here - ) 



user code 



top 



applic 




ARITHMETIC header? 



here 



origin 



Available 

dictionary space 

( applic here - ) 



arithmetic 'code 



user headers 



user code 



top 
applic 



here 



origin 



Available 

dictionary space 

( applic here - ) 



■arfth metis headers 



*7 arithmetic code 



user headers 



user code 



" addto user 



addto arithmetic " 



addto function 



user vocabulary is open. 



arithmetic vocabulary is open. 



function vocabulary is open. 



3. Finally, the new vocabulary's token and its parent token 
are stored in the extant array. 

The Extant Array 

Each vocabulary in the dictionary has its token and the token of 
its parent vocabulary in an array called 'extant'. Each entry in 
the extant array is 4 bytes in length and consists of a 2-byte 
token for a vocabulary followed by a 2-byte token for the 
vocabulary's parent vocabulary. The extant array is 64 bytes 
long and therefore has enough room for 16 child-parent vocabulary 
pairs. Execution of the word extant will return the address of 
the extant array. 

The extant array is used by tForth words which must remove 
vocabularies from the system. 
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RUNNING tFORTH 

The first part of the tForth technical manual dealt with the data 
structures and memory usage and layout of the tForth system. 
This part of the technical manual will cover the dynamic 
functioning of the tForth system. 

The Word quit 

The main word which 'runs' FORTH is quit . These are the basic 
actions performed by quit : 



quit ( - ) 
begin 



( clear the return stack ) 
( get a block of user input text ) 
( interpret the user input text ) 
." ok" cr 



again 



Clearing the return stack is simply a matter of returning the 
return stack pointer to its base position, query t which was 
discussed previously in the string I/O section, is used to get a 
line of input text from the user. The most important word used 
by quit is interpret . interpret is responsible for parsing the 
input stream. 

The tForth definition for interpret is shown on the following 
page, interpret is passed the address and length of the input 
text on the parameter stack. In the first two lines of interpret 
the end address of the input text is stored in the system integer 
limit and the start address of the input text is stored in the 
system integer in . The in integer is used to mark interpret' s 
progress through the input text string. 

These are the actions which occur in the main 
'begin. . .while. . .again' loop in interpret : 

1. word is used to extract the next word (sequence of 

characters delimited by spaces or tabs) from the input text, 
word will leave the address of the extracted word in the 
system integer str, the length of the extracted word in len , 
reposition the in integer to point to the next character to 
be examined in the input text. 
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interpret ( 
over 
in to 
begin 

len 

while 



a 1 ■ 
limit 



word 



locals 
if 



) 
to 



else 



then 



doloc 



-1 



begin the interpretation loop ) 
grab a word from the input text ) 

while the length is nonzero ) 

is this word a local variable? ) 

IF it is, perform special local variable ) 

actions, described later ) 



if 



str 

?dup 

if 



else 



{ if the word is not a local variable, ) 
( try to find it in the dictionary ) 
len find 

( if the word was found in the dictionary... ) 

0< state nesting or and 

if { and if the system is in the ) 

( compiling state, compile the word ) 

compile, 
else ( otherwise, execute the word ) 

sw execute sw 
then 

( if the word was not found in the ) 
( dictionary, try to convert it to a number ) 
str len base number 
if ( if it is a number... ) 
state nesting or 
if 
( and compiling state is on ) 
( compile # as a literal ) 
[compile] literal 
else 

{ leave # on param stack ) 
then 
else ( if its not a #, check for targeting ) 
targeting 
if 

( if targeting is occurring. . . ) 
forward 
else 

{ leave the loop and abort ) 
leave 
then 
then 



then 



then 
?stackerr 
again 
len abort" can't use" 



{ check the parameter stack state ) 
{ can't use this word ) 
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2. If word is able to extract a word from the input text, it 
will drop into the while section of the 

begin. . .while. . .again loop. The first test performed in the 
while section is a test to see if the extracted word is a 
local variable. If the word is a local variable, local 
variable type actions occur (described later) and a false (0) 
flag is left on the parameter stack. If the word is not a 
local variable, a true (nonzero) flag is left on the stack. 

3. If the word was not a local variable, interpret checks next 
to see if the word can be found in the dictionary using the 
current search order, find is used to locate words, 
specified by the address and length of their name strings , in 
the dictionary. If find finds a word it returns the token 
for the word and a true (nonzero) flag on top of the 
parameter stack. If the word found is an 'immediate' word 
the flag returned will be a ' 1'. Otherwise, the flag 
returned will be a '-1'. If find cannot located a word, it 
returns a false (0) flag. 

4. If the word was found in the dictionary, interpret must next 
decide whether the word should be compiled or executed. Two 
tests must be true in order for the word to be compiled. 
First, the word found must not be an immediate word. Second, 
one or both of the two system integers state or nesting must 
contain a nonzero value. If the state system integer 
contains a nonzero value it means the system is in the 
compilation state. If the nesting system integer contains a 
nonzero value it means the system is currently compiling the 
temporary code required for interactive execution of program 
control structures (discussed later). So, if the word found 
is not immediate AND if the system is either compiling real 
definitions OR compiling temporary code for interactive 
execution of program control structures, the token for word 
will be compiled. 

5. If the conditions for compilation are not met, execute will 
be used to execute the word corresponding to the token. 

6. If the extracted word was not found in the dictionary, 
interpret will next try to convert the string to a number. 

If the string can be converted to a number, and the system is 
either in the compiling state OR compiling temporary code, 
the number will be compiled into the current definition as a 
literal. 

7. If the string was converted to a number and the system is not 
compiling, the number will be left on the parameter stack. 

8. If the extracted word was not a word in the dictionary and 
could not be converted to a number interpret will check to 
see if the system is currently in the target compiling state 
by checking the contents of the targeting system integer for 
a nonzero value. If target compilation is occurring (target 
compilation will be discussed in a separate document) , the 
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extracted word will be compiled into the target system image 
under construction. Otherwise, leave will be used to exit 
the loop, interpret will abort , and an error message will be 
issued. 

Now that the general actions of a running tForth system have been 
described, individual aspects may be discussed in detail. The 
following aspects of the tForth system will be covered in the 
final sections of this technical reference manual: 

* The Basics of tForth Compilation 

* Execution of Token-Threaded Code 

* The Implementation of tForth' s Integers 

* The Implementation of tForth* s Local Variables 

* The Implementation of tForth 's Program Control Structures 
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THE BASICS OF tFORTH COMPILATION 

Structure of a Dictionary Entry 

In the "Under the Hood" chapter of Leo Brodie's book Starting 
Forth , the structure of a dictionary entry in an address -threaded 
FORTH implementation is described. Since the original 
implementation of FORTH, and most FORTH implementations for many 
years after, were address -threaded implementations, the 
address-threaded model of FORTH is generally considered to be the 
'standard'. In recent years, FORTH implementors have devised 
many different threading schemes. The token- threading scheme 
used in tForth is one of the most popular of the new FORTH 
threading schemes due to its conservative use of memory. In this 
section, tForth 's token threading scheme will be explained by 
comparing it with the 'standard' address threading scheme as 
described in Starting Forth . 

The diagrams on the following page show the dictionary entries 
which would be created for the definition below in a 32-bit 
address- threaded implementation and in the 32-bit tForth 
token- threaded implementation: 

: newword { n - ) 

3 * dup + . ; 

Certain areas in the diagrams have been given the following 
labels since, according to Starting Forth , all Forth definitions 
share these common parts: 

DEFINITION DEFINITION 

HEADER FIELDS CODE FIELDS 

name field code pointer field 

link field parameter field 

The 'definition header fields' are used to find definitions in 
the dictionary (in order to execute or compile the definition) . 
The 'definition code fields' are used when a definition is 
executed. In the tForth implementation the definition header 
fields and the definition code fields are stored in different 
memory areas. The token field and the token table, which will be 
described in more detail later, are used to link a definition's 
header and code fields together. 

The 'code pointer' field is used to specify where the 'code' for 
the definition is located. The parameter field contains either 
data, addresses (in an address threaded implementation) , tokens 
(in a token threaded implementation), or machine code 
instructions. 
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Dictionary Entries: Address Threaded versus Token Threaded 

; newword ( - ) 3 * dup + . ; 



Address Threaded 

Definition 

Header 

Fields: 



Definition 

Code 

Fields: 





{immediate bit 




bwer 


i| 7 ! n 


) 




memory 


e \ w 


name field 




w J 




r * d 








link field 






code field 




address of literal 


/ 






00000003 






address of * 






address of dup 


parameter field 




address of + 






address of . 




higher 
memory 


address of ; 





Token Threaded 

Definition 

Header 

Fields: 



lower 
memory 



higher 
memory 



dictionary search bit 
immediate bit 
reserved 




•11 7 » n 


e \ w 


w » 


r \ d 



token field 



name field 



Definition 

Code 

Fields: 



bwer 
memory 

higher 
memory 



JMP (np) 



blit token \ 03 



* token \ dup token 



+ token tierl token 



. token »<exit> token 



code field 



parameter field 



2 bytes 



In an address threaded implementation, the dictionary is 
organized into groups of linked lists (one for each vocabulary) . 
The 'link* field for each word in the dictionary points to (holds 
the address of) the previous dictionary entry in a particular 
vocabulary list. 

In the tForth implementation, the link field has been eliminated 
because the words in each vocabulary are arranged alphabetically. 

Examining the Definition Header and Code Areas 

The tForth compilation word n' ('n-tick') can be used to find the 
address of the definition header for a word: 

n' newword 10 dump 

5FFBA 07 2C 87 6E 65 77 77 6F 72 64 7F 7F 8l 7F 4E D3 .,. newword N. 

The two leftmost bytes are the encoded token value for newword. 
The next byte is the length byte for newword' s name. The length 
byte shows that there are 7 characters in 'newword'. The length 
byte looks like '87' because the most significant bit is set for 
dictionary searches (described later) . The next seven bytes 
contains the ASCII codes for the characters in the word newword. 
n' can only be used on words in the current open vocabulary. 

The tForth compilation word c 1 ('c-tick') can be used to find the 
address of the code for a definition: 

c 1 newword 10 dump 

478EC 4E D3 0A 03 77 2D 54 01 0C 10 00 00 00 1A 8l 00 N. . .w-t 



The contents of the code field for newword are located in the two 
leftmost bytes in the display. The parameter field contents 
occupy bytes 3 through 10 in the display. 

Tokens and the Token Table 

A token is a one byte number whose value can be any number 
between and 255 decimal. Each word in tForth is represented by 
either 1 or 2 tokens. The token field in a tForth definition 
header contains an encoded version of the definition's token 
value. To find the code which corresponds to a particular 
definition header, the encoded token value is decoded to its 
corresponding token value and then multiplied by four (since each 
entry in the table is 4 bytes long) and used as an offset into 
the 'token table* (see the diagram on the following page). The 
token table is a table which contains the 32 bit code addresses 
for all definitions known to tForth. 
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Token Table 



Tiers: 



+tabla — ► 



tierO 


tier 1 


tier 2 


tier 3 


tier 4 


tier 5 


tier 6 


tier 7 


tiers 


tier 9 



1024 bytes per tier, 
room for 256, 4 byte 
token table entries per tier 



unused token 
table entries 



Close up of the start of tier 0: 



token 00 
token 01 
token 02 
token 03 
token 04 
token 05 
token 06 
token 07 
token 08 
token 09 
token 0A 



entry 
entry 

entry 
entry 
entry 
entry 
entry 
entry 
entry 
entry 
entry 



code address for 'forth' 


code address for 'tierV 


code address for 'tier2' 


code address for 'tier3' 


code address for 'tier4' 


code address for 'tier5' 


code address for "tiers' 


code address for 'tier7' 


code address for 'tiers' 


code address for 'tier9 


code address for 'blit' 



+table 
+table 
+table 
+table 
♦table 
-t-table 
+table 
+table 

8 +table 

9 +table 
A +table 



4 bytes 



Useful Token-Related Words 

The words * ('tick*) and ['] ( 'bracket- tick-bracket* ) can be used 
to find the token value for a word. f is used outside of colon 
definitions and [*] is used within colon definitions. The word 
name will take a token value and display the name of the 
corresponding FORTH word. The word encode encodes a token value 
(for placement into the token field of a word's header) and the 
word decode decodes an encoded token value (so the decoded token 
can be used as an index into the token table) . The word ♦ table 
takes a decoded token value and returns the address of the 
location in the token table where the corresponding code address 
is stored. 



' newword . 3 AC 
3AC name newword 

3AC encode . 120 
72C decode . 3AC 
3AC + table . 46EBO 



46EBO @ 



478EC 



newword 



478EC 



get newword 's token value ) 

find which FORTH word belongs to ) 

the token 3AC ) 

encode the token value ) 

decode the token value ) 

get the address of newword' s entry in ) 

the token table ) 

fetch the contents of newword' s entry ) 

in the token table: the address where ) 

the code for newword is located. ) 

compare the address returned by c' ) 

with the address returned above, they ) 

are the same ) 



Note that the encoded value of newword' s token is the same value 
stored in newword 's token field (shown above in the n' example). 
Also note that the code address returned by c' is the same as the 
code address stored in newword 's token table entry. (Note, try 
using name to determine which FORTH words belong to the tokens in 
the parameter field area of the code portion of newword. See the 
c* example above.) 

Tiers 

Since a byte size token can only assume 256 distinct values, the 
use of single tokens only would limit the system to a maximum of 
256 words. To overcome this .limitation, the 'tiered' arrangement 
shown on the diagram was introduced. Each of the 10 tiers can 
hold 256 code addresses. This means the system can potentially 
accomodate 256*10=2560 words, although currently there are only 
about 1000 words. To locate a code address stored in tiers other 
than the base tier (tierO) requires the specification of the tier 
level and the token value. 

Example: Anatomy of newword 
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Let's examine the tokens compiled into the newword definition: 

c ' newword 10 dump 

478EC 4E D3 0A 03 77 2D 54 01 0C 10 00 00 00 1A 81 00 N...w-t. 



4ED3 Contents of code field, to be discussed later. 

0A Token for blit 

03 Literal data used by blit 

77 Token for * 

2D Token for dup 

54 Token for + 

01 Tier token 1 , indicates that the following token value 

is located in tier 1 in the token table 

0C Token for . , located in tier 1 

10 Token for <exit> 

References to all words except for . were compiled as single-byte 
tokens. Words compiled as single byte tokens are located in 
tierO in the token table. The word . is located in tierl in the 
token table. Words located in tiers other than tierO will be 
compiled as 2 byte token combinations. Token values 01 , 02 , 03 
, 04 , 05 , 06 , 07 , 08 , and 09 are all 'tier tokens' which 
correspond to tierl , tier2 , tier3 , tier4 , tier5 , tier6 , 
tier7 , tier8 , and tier9 in the token table. 

Compilation Size Considerations 

The compiled code for newword required 10 bytes of code space and 
28 bytes (7 tokens * 4 bytes per token table entry) of token 
table space. This means the token threaded version of newword 
requires a total of 38 bytes of memory. 

In an address threaded version of newword each of the 5 words 
referenced by newword would cause a 32 bit, or 4 byte, address to 
be compiled. This means the compiled code for an address 
threaded version of newword could require up to 24 bytes of code 
space (including the space required for the literal data) . 

If 5 words very similar to newword were to be compiled in the 
tForth token threaded system the memory requirements would be 50 
bytes of code space (10*5=50) and still only 28 bytes of token 
table space for a total of 78 bytes of memory. 

The same 5 words compiled in an address threaded system would 
require 120 bytes of code space (24*5=120) because in each 
definition the complete 4 byte addresses for each referenced word 
would have to be compiled. 
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Overall, tForth' s token threaded approach saves code space 
because the memory intensive data, the 4 byte code addresses for 
each word in the dictionary, are only located in one spot in 
memory - in the token table. Each compiled reference to a word 
only generates a one or two byte token in the code space. In an 
address threaded version the 4 byte code address for a word is 
repeated each time a reference to the word is compiled. 

The Compilation Process 

To study the compilation process, we will reconstruct the tForth 
and interpreter's and compiler's actions during compilation of 
newword . Here, once again, is the definition of newword : 

: newword ( n - ) 3 * dup + . ; 

For the sake of simplicity, assume the line containing the 
definition of newword has just been sent to tForth. The FORTH 
interpreter will start "walking" through the input line, 
separating out words (sequences of characters delimited by spaces 
or tabs) and executing them. The first word encountered by the 
interpreter will be the word : . This is what happens when : is 
executed: 

: 1. Calls create . create aligns the here pointer (which 

points to the location in the code space where the code 
for newword will be placed) on an even word boundary. 
Next, create uses word to get the next word from the input 
stream, which will be the name to be assigned to the new 
definition ("newword", in this case). Finally, create 
assigns a token to the new definition and creates a new 
dictionary header. 

2. Calls ] . ] saves the current contents of the nesting 
and state system integers and places zeros in both 
integers. The purpose of the nesting system variable will 
be discussed later in the technical discussion on program 
control structures, state is the system integer used to 
record the current 'state' of the system. If state holds 
a '0', the system is in the compiling state. If state 
holds a '1', the system is in the interpreting state. The 
net effect of 3 is to place the system in the compiling 
state. 

3. The final important action of : is to lay the first two 
bytes of code into the code area for newword . These two 
bytes contain the opcode for the assembly language 
instruction 'JMP (np) ' (4ED3) or, in human language, 
"execute the nest code definition". All definitions 
created by the defining word : begin with a 'JMP (np) ' 
instruction. 
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At this point, execution of : terminates and control returns to 
the interpreter. The interpreter grabs the words 3 t * t dup , + 
, and . from the input line. Since the system is now in the 
compiling state, due to the actions of ] , the the tokens for 
these words are compiled rather than executed. The final word on 
the input stream is ; . If the definition just compiled contains 
local variables, ; will compile the token for <;lp> into the 
definition. Otherwise, ; will compile the token for <;>. The 
implementation of local variables will be discussed in the 
technical discussion on local variables. At this point the 
interpreter has reached the end of the input line and newword has 
been compiled. 
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A7 
A6 


sp 
rp 


A5 


IP 



EXECUTION OF TOKEN-THREADED CODE 

How is a tForth word executed? Explanation of the tForth 
execution process requires that the tForth 68000 register usage 
is discussed and that some terminology is established. 

tForth Register Usage 

tForth uses 10 out of the 16 available 68000 registers to hold 
addresses it requires as it operates. 

REGISTER SYMBOL USAGE 

D7 bp Holds the address of the base of the 

token table. "base pointer" 
D6 iv Holds the address where the value of 

the current integer is stored. 

"integer value" 
D5 sa Holds the address of the start of the 

definition currently being executed. 

"start address" 
D4 ct Holds the address of the token table 

entry for the definition currently 

being executed, "current token" 

Parameter stack pointer. 

Return stack pointer. 

Holds the address of the next token to 

be executed in the current definition. 

"interpretation pointer" 
A4 nx Holds the address of the code for next . 

"next pointer" 
A3 np Holds the address of the code for nest . 

"nest pointer" 
A2 vp Holds the address of the run- time code 

for integer . 

The FORTH instructions generated by the tForth compiler are not 
executable 68000 instructions. The tForth compiler creates a 
virtual processor, with its own instruction set, which runs on 
top of the 68000 microprocessor. Since all 68000 instructions 
are at least 2 bytes in length and the tForth tokens are at most 
two bytes in length (the most popular tForth words are 1 byte 
tokens) , the instruction set for this virtual processor allows 
tForth to produce more compact code than it would if it always 
used the 68000 instruction set. Only the lowest level tForth 
words, the code definitions, consist of actual 68000 machine code 
instructions. 

The Word execute 

The word execute is used by interpret to execute FORTH words. 
execute executes the word corresponding to the token passed to 
it. To demonstrate how tForth words are executed, the steps 
taken by execute as it executes the word newword will be examined 



- 85 - 



newword ( n - ) 
3 * dup + . ; 
2 newword C 

' newword . 3 AC 
2 

3AC execute C 



( here is the definition of 

( once again ) 

( test newword out ) 



newword 



( get the token for newword ) 
( newword expects to be passed a ) 
( number on the stack when it executes 
( use execute to execute newword ) 



The code area for the newword definition is shown on the 
following page. The locations of some of the pointers mentioned 
above are shown in the positions they would hold just before the 
word newword is executed. 
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Token Threaded Execution 



Before execute : 



bp 



Token 
Table 



After execute 



( code area for newword ) 



4ED3 |0A|03|77|2Dl54|0l|0C[T0 



t 



( 'jmp (rip)' instruction ) 



ct-^aO 



bp 



newword entry 
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Table 
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Before 
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Token 
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4ED3 lOA|03|77|2D 54|Ol|OCrTo 



sa 



ip 



delta ip 



{ 6 ) 



( 7 ) 



Here is the code definition for execute : 

code execute ( n - ) 
sp )+ dO move, 

( code which checks to see if the token on the stack ) 
( belongs to a system integer goes here ) 

if, 

( special system integer ) 

( handling code, which will ) 

{ be explained in the next ) 

{ section, goes here. ) 



then, 



( 1 ) 


bp 


.b 


clr, 


{ 2 ) 


bp 


aO 


move, 


( 3 ) 


dO 


aO 


. w add , 


( 4 ) 


aO 


aO 


. w add , 


( 5 ) 


aO 


aO 


. w add , 



aO ) al move, 



al ) jmp , 



clear the lowest byte of the ) 

base pointer ) 

move a copy of the base pointer ) 

to the AO register ) 

multiply the token value times k ) 

and add the result to the copy ) 

of the base pointer to calculate ) 

the address of this token's token ) 

table entry ) 

put the contents of this token's ) 

token table entry- the code addr ) 

for the word corresponding to the ) 

token-in the Al register ) 

jump to the first instruction in the ) 

code area for this word ) 



;c 



The first part of execute checks to see if the token to be 
executed belongs to a system integer. Execution of system 
integers will be discussed later. The second half of execute 
contains the code responsible for the execution of tForth words. 
Since newword is not a system integer, the code in the second 
half of execute will be used. 

In the line marked line (1) above, the lowest order byte of the 
base pointer, which points to the start of the token table in 
RAM, is cleared. During tForth execution, the lowest byte in the 
base pointer is altered (as will be shown later). Clearing the 
lowest byte of the base pointer actually puts the base pointer 
back in its correct position. 



In line (2) , a copy 
the AO register. 



of the corrected base pointer is placed in 



In line (3), the word length decoded token value is added to the 
base pointer address. 

In lines (4) and (5) the decoded token value ($3AC for newword ) 
is added twice to the lower word of the copy of the base 
pointer. This has the net effect of multiplying the token value 
by k (4 bytes per token table entry) and adding the result to the 
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token table base address. The resulting address in the AO 
register is the address of the token table entry for the word to 
be executed (the address of newword' s token table entry) . Note 
that all of the addition operators use the '.w' (word length) 
suffix so that the upper word of the base pointer address is not 
affected by the addition operation. 

In line (6) the code address stored in the token table entry (the 
code address for newword ) is placed in the Al register. 

In line (7) program execution is vectored to the code area for 
newword by means of a 'JMP (Al)' or, "jump to the code for this 
word" instruction. 

Nesting 

As the diagram shows, the first field in newword's code area is a 
2-byte code field. The instruction in the code field is a 'JMP 
(np) ' instruction, newword t and all other tForth definitions 
created by the defining word : will have a 'JMP (np) ' instruction 
in their code field. In tForth the np (A3) register is used to 
hold the address of the tForth nesting routine (described 
below) . The nesting routine is always the first routine run 
whenever a colon definition is executed. 

In the 68000, each time a 'JSR' (jump to subroutine) instruction 
is executed, the address of the instruction at which execution 
should resume after the subroutine completes execution (the 
address of the instruction which immediately follows the 'JSR' 
instruction) is placed on the 68000 's system stack. The tForth 
processor is similar to the 68000 microprocessor in that 'return 
information* is saved away each time a 'jump 1 down to a lower 
level FORTH word occurs. The process of saving FORTH return 
information and 'jumping' down to a lower FORTH execution level 
is called "nesting" (don't confuse this term with the tForth 
system integer named nesting ) . In FORTH, the nesting process 
stops when a directly executable code definition is reached. 

The tForth nesting routine is used to make the transition between 
tForth execution levels. Each time a tForth word references 
another tForth word which is not a code definition, the system 
drops down to another execution level ('nests'). Any execution 
level can be completely described by two pieces of information: 
the delta distance from the start address of the definition 
currently being executed (kept in the sa register) to the address 
of the token currently being executed (see the diagram) , and the 
address of the token table entry for the definition currently 
being executed (kept in the ct register) . Here is a listing of 
the tForth nesting routine: 
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( 1 ) 



( 2 ) 
( 3 ) 

( 4 ) 



( 5 ) 
( 6 } 



frag .nest to ( create a code fragment, store the address of ) 

( the code fragment into the .nest system integer 



sa ip .w sub, 



ip 
ct 



rp 
rp 



-) 



move, 
move. 



al 2 )d ip lea, 



al sa move , 
aO ct move, 



calculate the distance between ) 

the start of the current code ) 

area to the token in the code ) 

area which is currently being ) 

executed ) 

save this delta away ) 

save the lower word of the ) 

current token pointer away ) 

put the address of first ) 

token to be executed in the ) 

lower level definition in the ) 

instruction pointer ) 

Al points to the start of the code ) 

area of the lower level definition ) 

AO points to the token field ) 

entry for the lower level defn. ) 



the 'next' code fragment starts here 



) 



( 9 ) 

{ 10 ) 

{ 11 ) 

( 12 ) 



ip )+ bp .b move, 



bp aO move , 
aO aO .w add, 

aO aO .w add, 

aO ) al move, 

al) jmp, 

c; 



place the token pointed to by ) 

the ip pointer into the lower byte ) 

of the base pointer ) 

calculate the address of the ) 

token table entry for the token ) 

just fetched ) 

get code addr. from token table } 

jump to the start of the code ) 

area for the new token ) 



The nesting routine code performs three functions. In the first 
half of the nesting routine, information about the previous 
execution level is saved away on the return stack (lines 1-3) arid 
the current execution level information is set up (lines 4-6) . 
The second half of the nesting routine (lines 7"12, also known as 
the 'next' routine), is responsible for starting the execution 
process going at the newly set up execution level (starting with 
the first token in the current definition) . 

At the end of the execute routine (described previously) , the Al 
register was left pointing at the code field for newword and the 
AO register was left pointing at the token table entry for 
newword . The state of these registers is reflected in the 
diagram. Discussion of the nesting routine as it relates to 
execution of newword will start at line (4) above. In line (4) 
the interpretation pointer, 'ip', is set up to point at the first 
token in newword' s parameter field area. This is accomplished by 
using the lea, instruction to add 2 to the address in the Al 
register. The nesting routine assumes that the code field in 
tForth is a 2 byte field. 

In line (5) newword' s code field address is placed in the start 
address pointer, 'sa 1 . In line (6) the address of the token 
table entry for newword is placed in the current token pointer. 
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' ct'. The 'ct' and ' sa' registers always hold addresses which 
pertain to the instruction which is currently being executed, in 
this case, newword . At this point, a new execution level has 
been completely established and the tokens in newword' s code area 
may be executed. 

The last half of the nesting routine (the next routine) performs 
the same functions as the last half of the execute routine 
described above. Both sections of code take a token, calculate 
its token table entry address, fetch its code address from token 
table, and vector execution to the first instruction in the code 
area for the token. The only difference between the two pieces 
of code is that in execute the token to be executed is passed in 
on the parameter stack and in the nesting routine the token to be 
executed is pointed to by the interpretation pointer. 

Executing a tForth Code Definition 

The first token to be executed in newword belongs to blit (token 
$0A) . blit is a code definition, so the code area for blit 
contains machine code: 



c 1 blit 10 dump 

11E6 10 ID 48 80 48 CO 2F 00 4E D4 70 00 12 ID 10 ID 



..H.H./.N.p. . 



101D 



4880 
48CO 
2F00 
4ED4 



ip 



dO 



move, 



dO .w ext, 

dO . 1 ext , 

dO sp -) move, 

nx ) jmp, 



get the byte value which follows ) 
the blit token and increment the ) 

ip ) 

extend it to a word value ) 
extend it to a long value ) 
push the value on the stack ) 
exit to FORTH ) 



Code definitions do not cause a change in execution level so the 
code field in code definition does not contain a jump to the 
nesting routine. The machine code instructions in blit's code 
and parameter fields are executed straight through. Since 
execution of a code definition did not cause any nesting to 
occur, termination of a code definition does not require any 
"unnesting" . Program execution simply continues with the next 
token in the definition. For this reason, a 'JMP (nx) ' 
instruction is used at the end of a code definition. This 
instruction causes the second half of the nesting routine, the 
part of the nesting routine which starts execution of the "next" 
token in the definition, to be executed. 

During execution of blit the ip was 'bumped' over the byte length 
literal data, $03- Therefore, the ip is currently pointing at 
the * token . * , dup , and + are also code definitions so this 
same cycle (jump to the code address, execute the machine code 
instructions, return to next) will be repeated three more times. 
Only when the token for tierl is executed does the execution 
cycle get more involved. 
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Tier Tokens 

The tForth interpreter steps through tForth definitions executing 
a single byte token at a time. The interpreter does not know how 
to execute 2 byte tokens. Single byte execution works fine with 
tokens numbered OO-FF hex (the tokens located in tierO of the 
token table). But what about the tokens in the rest of the 
tiers? Tokens in the other tiers would have token numbers like 
$123, $4A0, or $5FF, These numbers cannot be expressed as single 
byte values. The * tier words', tierl through tier9 (which have 
token numbers $01 through $09 and are located in tier 0) are 
special versions of execute which know how to execute words 
represented by tokens located in tiers 1 through 9. respectively. 

The token for the word . is located in tier 1 of the token 
table. References to . are compiled as a two-byte sequence: '01 
0C (see the previous diagram of the code area for newword) . The 
'01' is the tierl tier token, tierl 'knows' that the token which 
immediately follows it in memory, the *0C , is a token table 
entry number offset into tier 1 of the token table (rather than 
an actual token table entry number) . This token table entry 
number offset must be added to the base token number for its tier 
to calculate an actual token entry number. For example, the base 
token number for tier 1 is $100 (for tier 2 it is $200, for tier 
3 it is $300, etc) . The actual token table entry number for . 
would then be: $100 + $0C = $10C. Once a tier word has 
determined the actual token table entry number for a token, the 
token's token table entry address can be calculated and the code 
corresponding to the token can be executed. 

All of the 'tier words' are code definitions. The code 
definition for tierl is listed below: 
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3 


) 


dO aO move , 


{ 


4 ) 


aO aO .w add. 


( 


5 ) 


aO aO .w add, 


( 


6 ) 


aO ) al move, 



code tierl ( - ) 
{ 1 ) . tbl 100 + #n dO move, ( put address of base of token ) 

( table, plus 100 hex which is the ) 
( first token value in tierl , in the ) 
( dO register ) 
( 2 ) ip )+ dO .b mrve, ( get the next token, the token for . , ) 

$0C, and place in the lowest byte of the ) 
value in the dO register, now the lowest ) 
12 bits of the dO register contain $10C ) ( ( 
move the dO to the AO register ) 
calculate the address of the token table ) 
entry for . ) 

fetch the code address for . from . ' s ) 
token table entry ) 
7 ) al ) jmp, { jump to . 's code area ) 

When a tier token is executed it first adds the base token number 
for its tier to the base address of the token table (line 1 
below, the system integer .tbl holds the token table address). 
Next, the token table entry offset into the tier {i.e. the token 
value which immediately follows the tier token in the 
definition's code area, $0C in this example) is added to the 
previous result (line 2) . The last 5 lines of code in tierl are 
used to calculate the address of the token table entry in tier 1 
for . , to get the code field address for . , and to vector 
program execution to the code area for . : 

Words whose tokens are located in tiers 1 through 9 are compiled 
as a two byte token sequence. To conserve program space, the 
words in tForth have been arranged so that the most often used 
words are located in tierO. 

Nesting Down a Level 

Here is a listing of the code area for . : 

c f . 20 dump 

3E30 4E D3 2D 57 01 04 01 06 31 01 08 01 07 01 01 24 N.-W 1 $ 

3E40 10 FF 4E D3 01 04 01 06 01 07 01 01 24 10 20 IF . .N $. . 



2D 


name 


dup 


57 


name 


abs 


0104 


name 


<# 


0106 


name 


#s 


31 


name 


swap 


0108 


name 


sign 


0107 


name 


#> 


0101 


name 


space 


24 


name 


type 


10 


name 


<exit> 



is a colon definition so its code field contains a 'jump to 
the nesting routine' instruction. Execution of the nesting code 
will cause a change in execution level to occur. A change in 
execution level at this point means that the system will stop 
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executing tokens in newword and will start executing tokens in . 

Let's follow the transition between execution levels (refer back 
to the listing of the nesting code fragment) . 

Line 1: The delta between the start address of newword* s code 
area, held in the sa register, and the address of the 
token to be executed next, held in the ip register, is 
calculated and the result is left in the ip register. 

Line 2: The word length delta value is store in the return stack. 

Line 3: The lower word of the token table entry address for 
newword is saved on the return stack. 

Line 4: Put the address of the first token in . in the ip 

register. 

Line 5' Put the code field address of . in the sa register. 

Line 6: Put the address of the token table entry for . in the ct 
register. 

Line 7 : Fetch a copy of the first token in . , put the byte 

length token value in the bp register, and bump the ip 
pointer ahead one byte. 

Lines 8-12: Calculate the token table entry address for the 

token and vector program execution to the token's code 
area. 

Un-Nesting 

When . has completed execution, the final word to be executed in 
newword is <exit> (also called <;> ). <exit> takes two word 
length pieces of 'return' information off of the return stack and 
restore the execution-related registers so that execution may 
continue at a previous execution level. Here is the listing for 
<exit> : 
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code <exit> Parameter: ( 
rp )+ ct .w move, 



rp ) + aO . w move , 
ct al move, 
al ) sa move, 

aO sa xl)d ip lea 

next; 



) Return: ( nl n2 - ) 

replace the lower word of the ) 

current token table entry ) 

address with the lower word of ) 

of the token table address being ) 

used at the previous execution ) 

level ) 

remove the delta ip value from ) 

the return stack ) 

move the new token table entry ) 

address to the al register ) 

put the code field address found ) 

in the new token table field into ) 

the sa register ) 

( add the code field address to the 
delta ip value and place the ) 
resulting address in the ip reg. } 



Since newword was executed interactively using execute , the 
above use of <exit> will ' unnest 1 and allow execution of the main 
loop in quit , the 'interpret loop 1 , to continue. 



- 95 - 



THE IMPLEMENTATION OF INTEGERS 

Important Integer-Related Registers 

There are two registers which are directly related to the 
functioning of tForth's integers: the ' iv' and the 'vp* register 
(see below). The exact usage of these registers will be 
explained later in this section. 

REGISTER SYMBOL USAGE 

D6 iv Holds the address where the value of 

the current integer is stored. 

"integer value" 
A2 vp Holds the address of the run- time code 

for integer . 

Creating Integers 

The defining word integer is used to create new integers . 
integer is a defining word because it creates named (words with 
dictionary headers) child words and assigns run-time actions (the 
run- time action of a child word created by integer is to place 
its value on the stack) to the child word. Here is the 
definition of integer : 

: integer ( Compile time: n - j Run-time: - n ) 

create ( create a dictionary header for the ) 

( new integer ) 

4ED2 w, ( lay a 'jump to the address stored in ) 

( the vp register' instruction in the code ) 

( field of the child words code area ) 

, ( lay the 4 byte initial value for the integer ) 

( into memory immediately following the ) 

( 'jump' instruction ) 



12 integer fred ( create a new integer named fred ) 

r fred . 3B1 ( this is the token assigned to fred ) 

c' fred 10 dump ( display the contents of fred's code area ) 
47938 4E D2 00 00 00 12 31 84 66 12 65 64 07 32 83 6A N l.fred.2.j 

: testl ( - ) fred . ; { use fred in a colon definition ) 

( show how a reference to fred is ) 
c' testl 10 dump ( compiled into a colon definition } 
4793E 4E D3 03 Bl 01 0C 10 00 6B 81 00 07 36 85 64 6F N k...6.do 

In the first example above integer was used to create a new 
integer named fred . Then, ' was used to check the token 
number assigned to fred . Finally, c' was used to display 
the code area for fred . The code area for fred contains a 
'4ED2', or "jump to the address in the vp (a2) register" and the 
4 byte value , ' 00000012 \ of fred . 
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The second example above uses fred inside of a simple colon 
definition and then displays the contents of the colon 
definition's code area. The code area dump shows that integer 
references are compiled the same way as a references to other 
colon definitions are compiled, the token for the integer is laid 
into the code area of the colon definition. 

Execution of Words Created By integer 

The discussion of the tForth execution process showed that every 
colon definition contains a two byte machine code instruction, a 
"jump to the address in the np (a3) register (opcode = 4ED3)" , in 
its code field. During execution of colon words, execution of 
this special instruction would cause the tForth nesting routine 
to be run. 

The execution process for integers is very similar to the 
execution process for colon definitions. The vp, or a2, register 
in the V777 system is used to hold the address of the code 
fragment shown below. Whenever the token corresponding to an 
integer is executed, program execution will be vectored to the 
code field in the integer's code area. This will cause the 'JMP 
(vp) ' instruction to be executed and the code below will be run: 



frag .ramint to { - n ) 

1 ) 2 #n al addq, 

2 ) al ) sp -) move, 

3 ) al iv move, 

k ) ip )+ bp .b move, 

5 ) 

6 ) 

7 ) 



;c 



ip 


) + 


bp .b 


bp 


aO 


move, 


aO 


aO 


. w add , 


aO 


aO 


. w add , 


aO 


) 


al move , 


al 


) 


jmp, 



'point' al at the parameter field/ ) 

data for the integer ) 

push the integer's data on the ) 

parameter stack ) 

put the address of the integer's ) 

data in the iv register ) 

keep tForth execution going ) 

by causing the next token in ) 

the word which 'called' the ) 

integer to be executed... ) 



When execution of the .ramint code fragment starts, the al 
register will be pointing to the code field for the integer {see 
the diagram on the following page) . This position of the al 
register was described in detail in the section on the execution 
of token threaded code. In line 1 of the integer code above the 
address in the al register is repositioned so that it points at 
the start of the parameter field in the integer's code area. As 
the diagram show; the parameter field in an integer's code area 
is four bytes long and holds the current value of the integer. 
In line 2, the familiar run-time action of integers is 
performed: the integer's value is placed on the parameter 
stack. In line 3. the address where the integer's value is 
stored is placed in the iv register. Lines k through 9 are 
identical to the last 6 lines in the nesting routine. These 
lines are responsible for causing the next token in testl , the 
token for . , to be executed. 
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Integers Execution 



( code area for testl ) 



( *jmp (rip)' instruction ) 



4ED3 03 B1 01 0C 10 



( code area for fred ) 



( "jimp (vp)' instruction ) 



4ED2 |00 00 00 12 



t t 

a1 ar 

t 

iv 



How the Integer Operators Work 

Here is the code definition for and an example usage of to 

code to ( nl n2 - ) 

iv aO move, ( put the address of the integer's data ) 

( in the aO register ) 

4 #n sp addq, ( drop the top item, n2 - the integer's ) 

( current value, from the param stack ) 

sp )+ aO ) move, ( store the new value, nl, into the ) 

( integer's storage location ) 
next; 

5 fred to 

to should always be executed immediately after an integer (or a 
local variable) name has been executed. After an integer is 
executed, the integer's value will be on top of the stack and the 
address of the integer's storage location will be in the iv 
register. Since to is also passed the new desired value for the 
integer, there will be two items on the stack when to is 
executed, the current integer value will be on top of the stack 
and the desired new value will be second on the stack. 

In the first line of to the address of the integer's storage 
location is moved into the aO register. In the second line the 
integer's current value is dropped from the stack. In the third 
line the new value on top of the stack is stored into the 
integer's storage location. 

♦to is very similar to to : 



code +to { nl n2 
iv aO move , 

4 #n sp addq, 

sp )+ dO move, 
dO aO ) add, 

next; 

4 fred +to 



■ ) 

put the address of the integer's storage 

location in the aO register ) 

drop the current integer value from the ] 

parameter stack ) 

put the increment value in the dO reg ) 

add the increment value to the current ) 

value of the integer ) 



addr is even simpler than to 



code 

iv 



next; 



addr 
sp 



n 
move 



- a ) 



put the address of the integer's storage ] 
location in the top position on the param 
stack, write over the integer's current ) 
value ) 
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System Integers 

tForth and V777 system integers, integers which are used during 
operation of tForth or the editor, are implemented and executed 
in a completely different manner than integers created with the 
use of integer . 

The first difference between system integers and regular integers 
is that system integers are not created with integer . System 
integers are created with a special integer creation word which 
is not available for use in the editing environment. A second 
difference is that the values of system integers are located in a 
special 'tiered' integer data table. The final difference is 
that system integers have dictionary header entries for their 
names but do not have any corresponding dictionary code areas. 
The reasons for these differences are described below. 

The System Integer Tier Table 

The diagram on the following page shows how the system integer 
tier table is arranged. The tiered integer table is very similar 
to to the tiered tok i table. The system integer table has 9 
tiers, numbered through 8. Each tier is 256 (decimal) bytes in 
size (each tier in the token table is 1024 bytes in size) . 64 
4-byte system integer values can be stored in each tier (64*4=256 
bytes). The system integer table can hold a maximum of 576 
(64*9=576) system integer values. 
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System Integer Table 



Tiers: 



t 

$100 


tierO 
(1BXX tokens) 


$200 


tierO 
(1CXX tokens) 


$300 


tierO 
(1DXX tokens) 


$400 


tierO 
(1EXX tokens) 


$500 


tierO 
(1FXX tokens) 


$600 


tierO 
(20XX tokens) 


$700 


tierO 
(21 XX tokens) 


$800 


tierO 
(22XX tokens) 




tierO 
(23XX tokens) 



256 bytes per tier, 
room for 64, 4 byte 
system integer 
values per tier 



unused system 
integer entries 



Close up of the start of system integer tier 0: 



token 
token 
token 
token 
token 
token 
token 
token 
token 
token 
token 



1B00 
1B04 
1B08 
1B0C 
1B10 
1B14 
1B18 
1B1C 
1B20 
1B24 
1B28 



entry 
entry 
entry 
entry 
entry 
entry 
entry 
entry 
entry 
entry 
entry 



value for 'here' 


value for 'base' 







































offset 
offset 
offset 
offset 
offset 
offset 
offset 
offset 
offset 
offset 
offset 



$00 
$04 
$08 
$0C 
$10 
$14 
$18 
$1C 
$20 
$24 
$28 



4 bytes 



System Integer Token Assignments 

The value of the system integer here is located in the very first 
position in the system integer table. The value of the system 
integer base is located in the second position in the system 
integer table. The memory dump below shows how references to 
system integers are compiled into colon definitions: 

: test2 (-an) here base ; 

c' test2 10 dump 
479^0 kE D3 IB 00 IB Ok 10 00 6B 81 00 07 36 85 64 6F N k...6.do 

System integers are always compiled as a 2 byte token sequence 
(even if the system integer is located in tier of the system 
integer table ). here has been assigned the tokens 'IB' and 
'00'. base has been assigned the tokens 'IB' and '04' . Token 
values ' IB ' through ' 22 ' hex are assigned to the lower level 
system integer execution words intO through int8 . The system 
integer execution words perform functions which are analogous to 
those performed by the tier words ( tierl through tier9 ) 
discussed in the tForth execution section. Here is the 
definition of the system integer execution word intO : 

code intO { - n ) 

.int 000 + ( add the offset to system integer tier 0, ) 

( which is zero, to the base address of the ) 

( system integer table ) 

#n iv move, ( put the address of the start of system ) 

( integer tier in the iv register ) 

ip )+ iv .b move, 

( get this system integer's offset into tier 

( and add it to the address in the iv register ) 

( to determine the address of this system ) 

( integer's entry in the system integer table ) 

iv aO move, ( put a copy of the iv in the aO register ) 

aO ) sp -) move, ( fetch the system integer's data from its ) 

( entry in the system integer table ) 
next; 

intO uses a very simple equation to calculate the address of a 
system integer's storage location in the system integer table. 
The offset to tier in the system integer table is added to the 
base address of the system integer table (obtained by executing 
the word .int , which is not available for use in the editor 
environment). The offset to tierO is 0, the offset to tier 1 is 
100 hex, the offset to tier 2 is 200 hex, etc. The system 
integer's offset into a particular tier in the table is added to 
the base address of its tier to calculate the exact address of 
its table entry. When a reference to a system integer is 
compiled the first byte ('IB' through '22') is the token for the 
system integer execution word which corresponds to the integer's 
tier and the second byte ('00' for here and *04' for base ) is 
the offset from the start of the tier to the integer's storage 
location. 
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code 


execute ( 


n 


sp 


) + 


dO move 


\int 8 


shl 




#n 


dO 


.w cm 


P. 



Execution of System Integers 

The word execute contains special provisions for the execution of 
system integers. Here is the top half of the execute routine 
listed previously: 

) 

( get the token from the stack ) 

( form the value ' 1B00' hex ) 

( if the token value is greater than ) 

( or equal to 1B00 then the token ) 

{ belongs to a system integer ) 

shl - ( subtract 1B00 from the base ) 
( address of the integer table ) 
( now add the token value to the ) 
( previous result to calculate the ) 
( address of the integer's storage ) 
{ location ) 

{ fetch the system integer's value ) 
move, { and place it on the parameter ) 
( stack ) 



nc if, 



.int \int 8 
#n dO add , 



dO 


iv 


move, 


iv 


aO 


move, 


aO 


) 


sp -) 



next, 



then, 



If execute is passed the token value for a system integer, it 
performs the system integer functions immediately (place the 
system integer value on the stack and place the address of the 
system integer storage location in the iv register) . 
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THE IMPLEMENTATION OF LOCAL VARIABLES 

The word test3 below is a simple example word which demonstrates 
the usage of tForth local variables. In test3 three local 
variables, named 'one* , 'two 1 , and 'three' t are created and 
then referenced. The dump of the code area for test3 will be 
used as a reference during this discussion of the implementation 
of local variables: 

: test3 ( - n.l n2 n3 ) 

local one local two local three ( create 3 local variables ) 

1 one to ( put a 1 in one ) 

2 two to ( put a 2 in two ) 

3 three to ; { put a 3 in three ) 

c 1 test3 20 dump 

4?8DO 4E D3 14 0C 41 15 4F 0A 02 16 4F 0A 03 13 08 4F N. . .A.O. . .0. . . .0 

478EO 11 0C 13 08 11 0C 00 00 00 3A 8l 00 07 36 85 64 :...6.d 

4ED3 This is the machine code instruction compiled at 

the start of all colon definitions. 
Token for <locals> , data for <locals> 
Tokens for 1 (puts a 'l f on the stack), <loc0> , to 
Tokens for blit , data for blit , <locl> , to 
Tokens for blit , data for blit , <local> , data 
for < local > , to 

11 0C Token for <;lp> , data for <;lp> 

Execution of Words Which Contain Local Variables 

This section will briefly discuss how words which contain local 
variables are executed. test3 will be used as an example. 

The declaration of the first local variable in a word causes the 
token for the word <locals> to be compiled. The byte location 
which immediately follows <locals> is used to hold data used by 
<locals> . The listing below shows the run- time actions of 
<locals> : 



14 


OC 








41 


15 


4f 




0A 


02 


16 


4f 




0A 


03 


13 


08 


4F 



code <locals> ( - ) 
#n dO moveq, 
ip )+ dO .b move 



dO rp sub , 



clear the dO register ) 
get the byte of data which ) 
immediately follows <locals> ) 
create a local variable storage ) 
area on the return stack ) 



next, 



At execution time, <locals> is responsible for initializing the 
storage area to be used by the local variables used in the 
definition. The storage space for local variables is located on 
the return stack. When <locals> is executed, it subtracts the 
byte value which immediately follows it in memory, the byte value 
indicates how much local variable storage is required by this 
definition, from the current return stack pointer address (see 
the diagram on the following page). 
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Local Variable Return Stack Usage 



higher memory 



offset = 8 



offset = 4 



lower memory offset = 



return 



information 



storage for 
3rd bcal variable 
created {"three") 



storage for 

2nd local variable 

created ("two") 



old rp 



storage for 

1 st local variable 

created ("one") 



U— 2 bytes -H 



new rp 



This repositioning of the return stack pointer creates a "hole" 
in the return stack which will be used as the local variable 
storage area while the definition executes. The contents of the 
local variable storage area are not initialized to any value. 
Since test3 uses 3 local variables, which each require 4 bytes of 
storage, a 12 decimal byte storage location is set aside on the 
return stack. 

The next 3 tokens in test3 will place a * 1 * into the one local 
variable. f 4l f is the token for the word 1 . 1 will put a ' 1' 
on top of the parameter stack when executed. '15' is the token 
for the local variable word <locO> . The run- time actions of 
<locO> are: 



code <locO> ( - n } 
rp iv move , 



rp ) sp -) move, 



put the address of the storage ) 
location for the first local ) 
variable in the iv register ) 
put the contents of the first ) 
local variable on top of the ) 
param stack ) 



next; 



one was the first local variable declared in test3 . The 
storage location for the first local variable is always located 
at an offset of from the top of the return stack. Local 
variables act like integers. When a local variable is executed, 
its contents are placed on the parameter stack and the address of 
its storage location is placed in the iv register. Because local 
variables act like integers, the word to , whose token will be 
executed next, will be able to store the value * 1* into the local 
variable's storage location. The diagram reflects the effects of 
the execution of these three tokens. 

The next line to be executed is f 2 two to'. The corresponding 
k tokens to be executed are 'OA 02 16 4F' . '0A f is the token for 
blit . When blit is executed it will place the byte length data 
which immediately follows it in memory (the '02') on the 
parameter stack. '16' is the token for the local variable word 
<locl> . These are the run- time actions of <locl> : 



code <locl> { - n ) 
rp 4 )d aO lea, 



aO ) sp -) move, 
aO iv move , 



get the address of the second ) 
storage location in the local ) 
variable storage area ) 
put the contents of the 2nd ) 
storage location on the stack ) 
put the address of the 2nd ) 
storage area in the iv register 



next; 



The second local variable declared in a definition is always 
given storage at an offset of 4 bytes from the top of the return 
stack. Aside from the use of a different offset, the actions of 
<locl> are very similar to those of <loc0> . The contents of the 
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second storage location are placed on the parameter stack and the 

address of the second storage location is placed in the iv 
register. 

The next line of code to be executed is f 3 three to*. The 

tokens for this line are 'OA 03 13 08 **F' . The f 0A 03' causes a 

3 to be placed on the parameter stack during execution. The '13' 
is the token for the local variable word <local> : 



code <local> ( - n ) 
#n iv moveq, 
ip )+ iv .b move, 



next; 



rp iv add , 



iv aO move t 

aO ) sp -) move, 



clear the iv register ) 
put the byte of data which ) 
immediately follows <local> ) 
into the iv register ) 
calculate the address of this ) 
local variable's storage location 
and leave it in the iv register ) 

put the contents of the local ) 
variable's storage location on ) 
the parameter stack ) 



The third local variable, and all subsequent local variables 
declared in a definition, have the offset to their storage 
location on the return stack compiled into the definition 
immediately after the token for <local> . The storage location 
for the three local variable is located at an offset of '8' from 
the top of the return stack. The first two local variables 
declared in a definition use special words { <loc0> and <locl>), 
which take advantage of fast addressing modes, to access their 
contents. The contents of all other local variables are accessed 
using the more generic word < local > . 

The final two tokens in test3 , * 11 0C* t are used to clean up 
after, and terminate execution of test3 . '11' is the token 
for <;lp> , which is the special version of <;> compiled when 
a word which contains local variables is being terminated: 



code 



<;ip> 


( " ) 


#n 


dO moveq , 


ip ) + 


dO . b move 


dO rp 


add. 


rp ) + 


ct .w move 


rp ) + 


aO . w move 


ct al 


move, 


al ) 


sa move, 


aO sa 


xl)d ip 


next; 





lea, 



{ find out how much local variable ) 
{ space this definition used ) 
( reclaim the return stack space ) 
{ take the return information off ) 
{ of the return stack and use it ) 
( to restore the ip and sa registers 
( used during the previous ) 
( execution level ) 
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When a word which uses local variables is compiled, the last byte 
in the word's code area will contain a byte value which indicates 
how much local variable storage the word uses during execution. 
<;lp> uses this data to reclaim the return stack space when the 
word has completed execution. 

Compilation of Words Which Contain Local Variables 

local is the main word responsible for the creation of local 
variables: 

: local ( - ) 

locals 0= ( have any local variables been created ) 

( yet? if not, perform these special local ) 
( variable initialization processes... ) 
applic 0A - localvoc to 
emptyvoc 0A + localvoc 0A cmove 
compile <locals> 
here location to 

c, ( compile a 'spacer' byte ) 
then 

tokens >r ( save tokens value away ) 

locals tokens to ( put return stack offset into tokens ) 
word { get name for this local variable ) 

localvoc addr str len assign ( create header entry and ) 

( put offset in token field ) 
4 locals +to ( increment offset ) 
r> tokens to ; immediate ( restore tokens value ) 

locals is the system integer used to keep track of how much local 
variable storage space is required for the definition currently 
being compiled {the colon definition defining word : will 
always set the contents of locals to zero at the start of 
compilation of a new colon definition) . When compilation of a 
colon definition terminates, locals will hold a value which 
specifies the complete local variable return stack storage 
requirements of the definition. During compilation of a colon 
definition, the value in locals is used to determine the return 
stack offset for the local variable currently being declared. 

When local is used to create a local variable, its first action 
is to check the current value of locals . If locals contains a 
zero, it means that local is being asked to create the first 
local variable for a definition. The creation of the first local 
variable for a definition requires that the special 'first-local' 
initialization code, contained between the if and then in the 
definition of local, must be executed. This special 
'first-local' initialization code performs the following 
functions: 

1. Constructs an empty, temporary vocabulary, which is 
invisible to the rest of the system, and places it 
immediately below the current location of applic 
(see the "Opening and Closing Vocabularies" diagram). 
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2. Stores the address of this special vocabulary in the 
system integer localvoc 

3. Compiles the token for the word <locals> into the 
definition currently being created. 

4. Compiles a byte length 'spacer' (with a value of 0) 
into the definition. This spacer area will later be 
used to hold a value which indicates how much 

local variable storage is required by this definition. 
The address of the spacer location is stored in the 
system integer location 

This initialization code is performed only when the first local 
variable is created for a definition. The rest of the code in 
the local definition performs the normal functions of local : 

1 . assign is used to create a dictionary header entry 
( str and len hold the address and length of the 
name for the local variable) for the local variable 
in the special local variable vocabulary. 

2 . The contents of the locals integer are incremented 
by four to indicate that four more bytes of local 
variable storage space are required for this definition. 

The Words assign , tokens , and recycled token 

Local variables do not have any associated code area because the 
words <loc0> , <locl> , and <local> are used to perform 
the run-time actions of local variables. For this reason, the 
token field in a local variables header field is not used in a 
standard manner. Rather than holding an encoded token value, the 
token field in a local variable dictionary header is used to hold 
the offset to the local variable* s storage location on the return 
stack. 

To use the token field in this non-standard manner, local must 
perform some non-standard manipulations of the contents of the 
tokens system integer, tokens holds the next token value 
available for assignment to a new definition. The word assign 
is used by local to create a dictionary header entry for the 
local variable in the special, invisible dictionary header area. 
To fill in the token field of the dictionary entry assign calls 
recycledtoken . recycledtoken must perform four tests before 
it can decide which token value to return to assign : 

1. Is the system is undergoing target compilation? 

If it is, recycledtoken will return the current value of 
tokens to assign (the next token value available for 
assignment) and then will increment the tokens value by one. 

2. Is the value in tokens greater than the value in ramtokenO? 
The system integer ramtokenO holds the token value of the 
first word in the dictionary which is not a rom word. If the 
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value in tokens is greater than the ramtokenO value, the 
system is attempting to add a new word to the dictionary. 
Rather than immediately returning and telling assign to assign 
the value in tokens to the new definition, recycledtoken 
will first check all of the previously assigned ram token entries 
(starting at the ramtokenO entry and continuing to on to the 
last known assigned token table entry, the entry corresponding 
to the token value which is one less than the value in tokens ) 
to see if any of the entries have been freed up due to the 
removal of a word from the system (if a token has been freed, 
its corresponding token table entry will hold the code address 
of the word freetoken ) . If a token in this region is available 
for re-use, recycledtoken will return its value to assign 
otherwise, it will go ahead and return the value in tokens 

3. Are all available token table entries in the token table in use? 
If the value in tokens corresponds to a token table entry 
which would not fall within the known token table area, no 

more tokens are available for assignment to new words, the 
dictionary is full. recycledtoken should return a '0* if this 
situation occurs (although it seems to return a 1 -1' in the 
current listing) . 

4. Is the system trying to use the token field in a non standard 
manner? 

Tokens assigned to words in the roms cannot be purged or 
reassigned. Therefore, if the current value in tokens is less 
than the token value found in ramtokenO , the system is 
trying the dictionary header fields in some non-standard 
manner (as is the case with local variable headers where the 
token field in the header entry is used to hold the local 
variable's execution time return stack offset). In this case, 
recycledtoken will immediately return whatever value is 
currently in tokens to assign 

The listing for recycledtoken is shown on the following page. 
The word i' ('integer-tick') is a target compiler word which 
returns the storage address for the system integer whose name 
immediately follows it. The word tc' ('tee-see-tick') is a 
target compiler word which returns the code address for the word 
whose name immediately follows it. endtable is the system 
integer which holds the address of the end of the token table. 



recycledtoken ( - token ) 
i' tokens dl move, 
i' ramtokenO dO move, 
tc' freetoken #n d3 move, 
i' targeting tst, 
1 ne bra, 



get current contents of tokens ) 
get value of ramtokenO ) 
get code address for freetoken ) 
if targeting is on, return and ) 
increment tokens ) 
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dO dl cmp , 
1 It bra, 



dO dl sub , 

1 #n dO subq, 



begin, 



1 #n dO addq, 
bp d2 move , 
d2 .b clr, 

dO d2 add, 

d2 d2 .w add, 

d2 d2 .w add, 
d2 aO move , 
aO ) d3 cmp, 

eq if, 

dO sp - ) 

next, 
then, 



move, 



dl nt -until, 



i' endtable dl move, 
aO dl cmp , 

It if, 

-1 #n sp -) move, 
else, 

d3 aO ) move, 

1 :1 i' tokens #n aO move 
aO ) sp -) move, 
1 #n aO ) addi, 

then, 

next; 



tokens value - ramtokenO value 
if tokens value is less than ) 
ramtokens value, return and ) 
increment tokens ) 
tokens value - ramtokenO value 



look for a token to be recycled ) 
check all token table entries ) 
from the start of the token table ) 
to the entry corresponding to ) 
token value in tokens ) 
is the execution address of ) 
free token in any of the token ) 
table entries? ) 

aO holds token table entry addr ) 

does entry hold freetoken's code ) 

address? ) 

if so, recycled the token ) 

by returning its value to assign 

used recycled token ) 

check all token table entries ) 
until the token table entry ) 
corresponding to the value in ) 
tokens is reached ) 

get the address of the end of ) 
the token table ) 
has search reached the end of ) 
the table? ) 

out of tokens, return 0? ) 

put the address of freetoken ) 
in this token's entry ) 

( return the value in tokens ) 
new token ) 
increment tokens ) 



local takes advantage of the relationship between tokens and 
assign . Before local uses assign ( it saves away the 
current value of tokens and places the current value of 
locals (which holds the return stack offset for the current 
local variable) into tokens . The largest possible return 
stack offset which would be stored into tokens would be 252 
decimal because only 64 local variables are allowed per colon 
definition. The current value of ramtokenO is approximately 
939 decimal. Therefore, when assign is used by local , it 
does not assign a new token for the local variable. Instead, 
assign places the offset found in tokens directly into the 
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token field. After local has used assign, 
tokens is restored. 



the previous value of 



At the end of compilation of the first line in test3 (the line 
where all the local variable declarations are made) the test3 
code area would look like this: 



4ED3 

4ED3 



14 
00 



14 00 



This is the machine code "jump to the nesting routine' 1 

instruction which is compiled at the start of all colon 

definitions. 

This is the token for < locals > 

This is a hole which will be filled in later with the value 

which indicates how much local variable storage is used 

by this definition. 



The locals system integer would hold a 12 decimal at this point 
because 3 local variables, which each require 4 bytes of storage, 
were declared for this definition. The location integer would 
hold the address of the spacer, and the localvoc integer would 
hold the address of the temporary dictionary header area where 
the special local variable headers are located. The token field 
for one would hold a '0' since its storage location is located 
at an offset of '0' on the return stack. The token field for 
two would hold a '4' because its storage area is second on the 
return stack and the token field for three would hold an '08'. 

The Word doloc 

The remaining lines of test3 contain references to the newly 
created local variables. As interpret 'processes' these 
remaining lines (please refer the previous discussion on 'Running 
tForth) , it is constantly using the word doloc to see if the 
word just encountered is the name of a local variable. Here is 
the listing for doloc : 



code doloc 
localvoc 



if 



loops 



if 



( - f ) 

str len <find> 



'dup 



dup 4 = 



if 



drop 

compile <locl> 



can this word be found in the ) 
local variables vocabulary? ) 

if so, have any local variables ) 
or # loops* been used yet in this ) 
definition ) 

if they have, was this the second ) 
local variable created in this ) 
definition? ) 

if it is the second, compile a ) 

( special, fast local variable ) 
reference ) 



else 



compile <local> ( otherwise, compile the normal 
c, ( local variable reference ) 
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else 



then 



compile <locO> 



then 
drop 



( if this was the first local variable 
( created for this definition compile ) 
( a special, fast, local variable ) 
( reference ) 

( return a false flag to indicate ) 
{ that doloc handled this word ) 
{ so the word needs no further ) 
{ processing by interpret ) 



then 



In the first line, doloc uses <find> to check the special 
local variable vocabulary to see if the name specified by the 
string address and length found in str and len is the name of 
a local variable. This is the stack notation for <find> : 



<find> ( vocabaddr str len 
( vocabaddr str len 



addr token true flag | If found ) 
addr falseflag | If not found. ) 



The flag returned by <find> is checked first by doloc to see 
if the word was the name of a local variable. If the word is the 
name of a local variable doloc checks the token value, or for a 
local variable, the return stack offset (the reasons for the 
reference to the loops system integer will be explained in the 
next section on the implementation of program control 
structures). If the offset is 0, doloc 'knows* that the first 
local variable declared is being referenced so it branches down 
and compiles the token for <loc0>. If the offset is 4, the 
second local variable declared is being referenced so the token 
for <locl> is compiled. If the offset is greater than 4, the 
token for <local> , and the byte length offset, are compiled. 

Terminating the Compilation of a Word Which Contains Local 
Variables 



The word ; compiles the final two tokens in test3 
'OC, and backfills the spacer left in test3 : 



'll* and 



( - ) 

locals loops + 



'dup 



if 



else 



compile <;lp> 
c, 



compile <;> 



if locals contains a nonzero ) 
value then this word uses local ) 
variables ) 

if it does, compile the token for ) 
followed by the amount of return ) 
stack storage space required ) 

if this word doesn't use local ) 
variables compile the token for ) 
the normal colon definition ) 
termination word ) 

(continued) 
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then 

state off ( return to the interpretation state 

locals ( if this word used local variables \ 

if 

locals location c! ( store the amount of storage ) 

( space required in the spacer ) 

( location ) 
then 
locals off : immediate 
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IMPLEMENTATION OF PROGRAM CONTROL STRUCTURES 

The lists below show all tForth words involved with program 
control structures. The first list below shows all of the low 
level program control primitives which define the run- time 
actions of the program control words: 



<Obran> 


<bran> 


<loop> 


<*loop> 


< leave > 


<01eave> 


<branl> 


<0branl> 


<leavel> 


<01eavel> 


<do> 





The next group of words are those which execute during 
compilation and cause the words listed above to be compiled: 



back 






?pairs 


{loop} 


{while} nest 


unnest 


if 


else then 


do 


loop 


♦loop begin 


again 


until 


while leave 


Execution 


of Program 


Control Structures 



' begin . . . until ' loops 

The memory dump below shows the code area for the definition 
pcsl , which contains a simple 'begin. . .until' loop control 
structure: 

: pcsl { - ) 
begin 

?t 

until ; 

c' pcsl 10 dump 

WEA 4E D3 B3 18 FE 10 07 36 85 64 6F 7A 65 6E 07 31 N 6. dozen. 1 

4ED3 'jump to the nesting routine' machine code instruction 

B3 token for ?t 

18 FE token for <0bran> , data for <0bran> 

10 token for <;> 

Note that begin does not cause any tokens to be compiled. During 
compilation, begin leaves its address on the stack so that the 
until or again which will eventually follow can determine how far 
back they must branch during execution. This delta backwards 
jump distance is compiled into the definition immediately after 
the token for the low level conditional branching primitive 
<0bran> ('bracket-zero-bran'). The diagram on the following page 
gives a pictorial representation of pcsl . 
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A 'begin...untir Loop 



pest ( - ) begin ?t 



until 



4 


E 


D 


3 


B3 


18 


FE (-2) 


10 




4 


E 


D 


3 


?t 


<Obran> 


Z^ 


<;> 



Here is the listing for <0bran> : 

code <Obran> ( f - ) 
sp )+ tst, 
eq if, 

ip ) dO .b move, 

dO .w ext, 

dO .1 ext, 

dO ip add , 



next, 
then, 
1 #n ip addq, 



test the flag on the stack ) 
if the flag is zero execute the ) 
following instructions ) 
get the byte branch data ) 
extend it to word length ) 
extend it to long word length ) 
add the delta distance to the ) 
current instruction pointer ) 
address , execution will resume ) 
at the new address ) 
exit ) 

flag was true, leave the loop ) 
and continue execution at the ) 
token which immediately follows ) 
the byte branch data ) 



next; 



<0bran> is a conditional branching primitive because it will only 
cause a branch under certain conditions. During execution, 
<Obran> checks the flag passed to it on the parameter stack. If 
the flag is false (0) , a program branch will occur. Branching in 
high level tForth code involves modifying the instruction pointer 
(ip) so that it points at a different section of code. <0bran> 
uses the byte length data which immediately follows it in memory 
to determine the destination point for the branch. To calculate 
the destination address, the byte data is added to the address 
currently in the ip register. Before the byte data is added to 
the ip address, it is sign-extended to a long word. 

If the flag passed to <0bran> is true (nonzero), a program branch 
will not occur. The code between the if, and then, above, 
the code responsible for performing the branch, is not executed. 
Instead, the code which follows the then, is executed. This 
code adds 1 to the instruction pointer so that the byte branch 
data is skipped. When a true flag is passed to <0bran> , the 
instruction pointer will be left pointing to the token which 
immediately follows the branch data. 

During execution of pcsl , <0bran> will check the flag left on 
the stack by ?t . If the flag is true (nonzero) , the jump back 
to the beginning point will be skipped and execution will 
continue immediately outside of the loop. If the flag is false 
(0) , the branch back to the start of the loop will be taken. 
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begin. . .while. . .again Loops 

The definition pcs2 below contains a 'begin. . .while. . .again' loop: 



pcs2 ( n - ) 
begin 

dup 1- swap 



while 

again 
drop 



dup 



begin ... ) 

duplicate the number on top of ) 
the stack, subtract 1 from the ) 
duplicate, swap the values ) 
while the value is not zero...) 
duplicate it and display it ) 
back to the top ... ) 
drop the seed ) 



c f pcs2 10 dump 

478FO 4E D3 2D 3B 31 18 06 2D 01 0C 17 F7 2F 10 6E 07 N. -; 1 ..-..../ .n. 

4ED3 'jump to the nesting routine* machine code instruction 

2D 3B 31 tokens for dup , 1- , swap 

18 06 token for <0bran> , data for <0bran> 

2D 01 0C tokens for dup , . 

17 F7 token for <bran> t data for <bran> 

2F token for drop 

10 token for <;> 

When while is used in a begin loop it also causes the low level 
word <0bran> to be compiled (see the diagram on the following 
page) . If the flag passed to <0bran> at execution time is 
false (0), the branch out of the loop { ' <0bran> deltal') will be 
taken. If the <0bran> flag is true (nonzero), the code which 
immediately follows *-he <0bran> data, the code between the 
while and the agai , will be executed. 

The again causes a new unconditional branching primitive, 
<bran> ('bracket-bran'), to be compiled: 



get the byte delta branching data ) 
extend to a word delta value ) 
extend to a long word delta value ) 
add the delta offset to the ) 
instruction execution address to ) 
calculate the address at which ) 
execution should continue after ) 
the branch ) 



code 


<bran> 


( " 


) 






ip ) 


dO 


b 


move, 




dO .w 


ext 








dO .1 


ext 







dO ip add , 



next; 



Execution of <bran> will always cause a branch in execution to 
occur. The delta branch distance to be used for the branch is 
located in byte in memory which immediately follows the <bran> 
token. <bran> sign extends the byte value to a long word value 
and adds the sign extended value to the instruction pointer 
address to calculate the destination address for the branch. 
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A 'begin. ..while. ..again' Loop 



pcs2 ( - ) begin dup 1- swap while dup 



until 



drop ; 



4 D 3 


2D 


3B 


31 


18 


06 


2D 


01 OC 


17 


F7(-9) 


2F 


10 



4 E D 3 


dup 


1- 


swap 


<0bran> 


Z\1 


dup 


• 


<bran> 


Z±2 


drop 


<;> 



ZS.1 



Z^2 



if .. .else. . .then Conditonal Structures 

The word pcs3 uses the 'if .. .else. . .then' program control 
structure: 



pcs3 ( 
if 

else 

then 



f - ) 



if the flag is true... ) 

. . . display a 3 ) 

otherwise. . . ) 

. . . display a 5 ) 

and always display a 7 ) 



c' pcs3 10 dump 

478FE 4E D3 18 07 0A 03 01 0C 17 05 0A 05 01 0C 10 07 N. 



4ED3 'jump to the nesting routine' machine code instruction 

18 07 token for <0bran> , data for <0bran> 

0A 03 token for blit , data for blit 

01 0C token for . 

17 05 token for <bran> , data for <bran> 

0A 05 token for blit , data for blit 

01 0C token for . 

10 token for <;> 

The diagram on the following page demonstrates how the 
1 if .. .else. .. then' structure works. The ' if .. .else. . .then* 
structure uses the familiar <0bran> and <bran> branching 
primitives, if causes a conditional forward branch to be 
compiled. If the flag passed into pcs3 is true (nonzero) t the 
first branch shown in the diagram will not be taken and the code 
between the if and the else will be executed, else causes 
the unconditional <bran> instruction to be compiled. The 
<bran> instruction terminates execution of the code between the 
if and the else and unconditionally reroutes program execution 
to the code which follows the then 

If the flag passed into pcs3 is false (0) , the first branch in 
the diagram will be taken and program execution will be rerouted 
to the code which immediately follows the ' <bran> delta2' tokens 
compiled by else . 
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An 'if...else...then' Loop 



pcs2 ( - ) if 



else 



then ; 



4 E D 3 


18 


07 


0A 


03 


01 OC 


17 


05 


OA 


05 


01 OC 


10 



4 E D 3 


<Obran> 


^ 


blit 


03 


■ 


<bran> 


j£±2 


blit 


05 


• 


<;> 



Z±2 



Z^1 



do.. .loop and do...+loop Control Structures 

The pcs4 definition below uses the 'do... loop' program control 
structure: 



pcs4 ( 



10 do i drop loop 



c' pcs4 10 dump 
4790E 4E D3 0A 10 40 0D 39 2F 0E 10 7A 65 6E 07 31 84 N. . .6.9/. .zen.l. 

4ED3 'jump to the nesting routine' machine code instruction 

0A 10 token for blit , data for blit 

40 token for 

0D token for <do> 

39 2F tokens for i , drop 

0E token for <loop> 

10 token for <;> 

The 'do... loop' structure does not required the compilation of 
branching data. The branching data used by a 'do... loop' is 
passed on the stack at execution time. This is the code 
definition for <do> ('bracket-do'): 



code <do> ( nl n2 ■ 

ip rp -) move, 

sp ) + dO move t 

sp )+ dl move, 

dl rp -) move, 

dl dO sub, 



dO rp - ) 



move, 



) 

save branching data, the address of the ) 

start of the 'do... loop', on the ret. stack 

get the start value for the loop ) 

get the limit value for the loop ) 

move the limit value to the return stack ) 

calculate the number of times the loop ) 

should be executed: start - limit , a ) 

negative value ) 

move the loop count to the return stack ) 



next; 



During execution, the <do> program control primitive takes two 
numbers from the parameter stack, the loop limit and start value, 
and places three items on the return stack, the start loop 
address, the loop limit value, and the negative loop count. The 
values on the return stack are used by the corresponding <loop> 
('bracket-loop') or <+loop> ('bracket-plus-loop'). The listing 
for <loop> is : 



code <loop> ( 



) 



1 #n rp ) addi, ( Increment the negative loop count by 1 ) 
eq if, 

6 #n 

6 #n 

next. 



rp 
rp 



addq, 
addq, 



( get rid of the 12 bytes of loop 
( info on the return stack ) 



then, 
rp 8 



next; 



d ip move, ( fetch the address of tL ; start ) 

( of the 'do... loop' out of the ) 

( return stack frame and place ) 

( the address in the ip register ) 
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<loop>'s first action is to subtract one from the number on top 
of the return stack, the loop count. If the loop count has 
reached zero, the code between the if, and the then, , which 
is responsible for removing the 12 bytes of data placed on the 
return stack by <do> from the return stack, is executed. If 
the loop count has not reached zero the code which follows the 
then, , which gets the address left on the return stack by 
<do> and places it in the ip register, is executed. The address 
left on the return stack by <do> is the address of the start of 
the 'do... loop'. Placing this address in the ip register causes 
program execution to be rerouted back to the start of the 
'do... loop'. A picture of the pcs4 execution time return stack 
frame and code area are shown on the following page. 
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Using while in do. . .loops 

The word while can be used in either the begin looping structure 
or in the do looping structure. When while was used in a begin 
loop above, it caused the <0bran> conditional branching primitive 
to be compiled. Since a conditional exit from a 'do... loop' is 
more involved than a conditional exit from a begin loop (the 
return stack must be cleaned up when exiting a 'do... loop', see 
the listing for <loop> ) , while will compile a different 
conditional branching primitive when used inside of a 
' do . . . loop ' . pcs5 shows how while could be used in a ' do . . . loop ' 
program control structure: 

: pcs5 { - ) 

10 do { go from to 10 ) 

i 6 < {is the current loop index less than 6? ) 

while ( while it is less than 6. . . ) 

i . { print the current loop index ) 
loop ; 

c' pcs5 20 dump 
47918 4E D3 0A 0A 40 0D 39 0A 06 74 26 05 39 01 0C 0E N...@.9..t&.9... 
47928 10 66 72 65 64 07 32 83 6A 6F 65 07 2C 84 70 63 .fred.2. joe. , .pc 

'jump to the nesting routine' machine code instruction 
blit t data for blit , token for 
<do> 

i , blit , data for blit , token for < 
<01eave> , data for <01eave> 

i , • 
<loop> 

<;> 

The word <01eave> { 'bracket-zero- leave ' ) is compiled when a 
conditional exit out of a 'do... loop' structure is required. 
<01eave> , like <0bran> and <bran> , expects a byte of 
branch data to immediately follow it in memory (see the diagram 
on the following page) . If the flag passed to <01eave> is true 
(nonzero), this byte of data will be skipped over (see the last 
line in the <01eave> code definition below) and the code which 
immediately follows the branch data will be executed (the code 
between the while and the loop in the pcs5 example). If 
the flag passed to <01eave> is false (0) , the code between the 
if, and the then, below will be executed. This code adds the 
byte branch data to the instruction pointer, to calculate the 
branch destination address, and then removes the 12 bytes of 
looping information from the return stack. In the pcs5 
example, the branch destination is the code which lies just 
outside of the 'do... loop' control structure. 
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A do. ..while. ..loop structure 



pcs5 



10 



do 



while 



loop 



4ED3 


blit 


10 


40 


<do> 


i 


blit 


06 


< 


<0bran> 


^1 


i 


• 


<loop> 




<> 



4ED3 



0A 



0A 



40 



0D 



39 



OA 



06 



74 



26 



05 
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code <01eave> ( f - 
sp )+ dO move, 
eq 



if, 
ip 



) dO 



dO ip idd , 



#n 
#n 



rp 
rp 



next. 



then, 

1 #n 



ip addq , 



) 

( get flag from the parameter stack ) 

( if the flag is false, a branch will occur 
.b move { get the byte length branch ) 
( offset from the next byte ) 
( location in memory ) 
( calculate the destination address ) 
( for the branch ) 

( remove 12 bytes of information ) 
( from the return stack ) 



( 'bump' the ip pointer ) 



add, 
add, 



next; 



leave 'ing From Program Control Structures 

The word leave is used to exit immediately and unconditionally 
from the current 'begin' or 'do... loop' program control 
structure. When leave is used inside of a begin loop it compiles 
the unconditional branching primitive <bran> . When leave is 
used inside of a 'do... loop' however, it must use the special 
<leave> unconditional branching primitive: 



pcs6 ( - ) 
10 do 
i 7 
if 



then 



loop 



leave 



perform this loop ten times ) 
does the loop index equal 7? ) 

if it does, leave this loop ) 

if it doesn't, loop back to the top of ) 
the loop ) 



c ' pcs6 20 dump 
4792A 4E D3 0A 10 40 0D 39 0A 07 70 18 03 25 02 0E 10 N. . .@.9. .p. .% 



4ED3 

0A 10 40 

0D 

39 0A 07 70 

18 03 

25 02 

0E 

10 



'jump to the nesting routine' machine code instruction 
token for blit , data for blit , token for 
token for <do> 
tokens for i and blit , data for blit , token for 



token for <0bran> 

token for <leave> 

token for <loop> 

token for < ; > 



data for <0bran> 
data for <leave> 



Here is the listing for <leave> 



code <leave> { - ) 
#n dO moveq, 
ip ) dO .b move, 
dO ip add , 



6 #n rp addq, 
6 #n rp addq, 



next; 



get the branch data ) 

calculate the branch destination ) 

address ) 

remove the 12 bytes of ) 

'do... loop' data from the stack ) 
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<leave> points the instruction pointer at the first instruction 
outside of the 'do... loop 1 and clears the 12 bytes of 'do... loop' 
data from the return stack. 

The diagram on the following page illustrates the execution 
process for pcs6 . If the flag passed to <Obran> is false (0) , 
the <0bran> branch will occur and the instruction pointer will be 
routed past the <leave> token to the <loop> token. If the flag 
passed to <0bran> is true (nonzero) , the <0bran> branch will be 
skipped over and the <leave> branch will occur. Execution of the 
<leave> token will cause the instruction pointer to be altered to 
point at the <;> token, which is the first token outside of the 
current ' do . . . loop ' . 
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A Note About Long Branches 

In the examples above, the compiled branch data used by the 
branching primitives words was 1 byte in length. This means that 
these primitives may only be used to branch to locations that are 
within 256 bytes of the start location for the branch. <branl> 
, <Obranl> ( <leavel> , and <01eavel> are versions of the 
branching primitives described above which support the use of 
longer branch distances. Each of these 'long' versions of the 
branching primitives will be followed in memory by 2 bytes of 
branching data. Therefore, the long forms of the branching 
primitives support branches to locations which are up to 32K 
bytes away from the branch start address. 

The listing for the <0branl> primitive should adequately 
demonstrate the functioning of all of the long branching 

primitives: 



code <0branl> ( f - ) 
sp ) + dO move , 
ne if, 

2 #n ip addq, 

next, 
then, 

ip )+ dO .b move, 
8 #n dO .w lsl, 



ip ) dO .b move, 



dO .1 ext, 

dO ip add , 
next; 



get the flag from the stack ) 
if the flag is false... ) 
. . . skip over the 2 byte ) 
branch data ) 

if the flag is true get the 1st 

byte of the branch data and ) 

shift it into the 2nd byte of ) 

the dO register ) 

get the second byte of the ) 

branch data and put it in the } 

least significant byte of dO, ) 

now the 2 bytes of branch data 

are in the lower 2 bytes of the 

dO register ) 

extend the branch dat- to a ) 

long word ) 

add the branch data to the ) 

instruction pointer ) 



The main difference between the short and long versions of the 
branching primitives is that the long versions work with two byte 
branching data and the short versions work with one byte 
branching data. 

Interactive Execution of Program Control Structures 

When a program control structure, or a set of nested program 
control structures, is executed interactively (when it is used 
outside of a colon definition) execution will commence as soon as 
the outermost program control structure is closed. For example, 
the interactive execution of a single level 'do... loop' would 
begin as soon as the closing loop is entered. Interactive 
execution of a 'do... loop' nested within an ' if .. .else. .. then' 
program control structure would begin as soon as the then which 
closes the outer 'if... then' structure is entered. 
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A do.. .if.. .leave then. ..loop 
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During the interactive use of program control structures, the 
system goes into a 'temporary compilation' state. Code is 
compiled in the code area of the dictionary until the outermost 
control structure is closed. As soon as the outermost control 
structure is closed, the temporary code is moved from the 
dictionary to an interactive program control structure execution 
buffer and executed. The address of the interactive execution 
buffer is kept in the system integer execbuf 

tForth uses two system integers to determine if program control 
structures are being used interactively, nesting and state 
nesting is used to hold a count of how many program control 
structures have been nested inside of the outermost structure. 
Each time a word which starts a program control structure ( if 
, do , begin ) is used, the contents of the nesting system 
integer are incremented by one. Each time a word which ends a 
program control structure ( then , loop , +loop , again , 
until ) is used, the contents of the nesting system integer are 
decremented by one. If program control structures are used 
correctly, nesting should always hold a zero when the outermost 
structure is closed. 

state is used to keep track of whether the system is in the 
interpretation or compiling state. If state holds a zero, the 
system is in the interpretation state. Whenever the nesting 
integer holds a nonzero value while the state integer holds a 
zero, the system is performing the temporary compilation required 
for the interactive execution of program control structures. 

nest 

As the definition of nest shows, execution of nest will 
always cause the nesting contents to be incremented by one. 
If nest is used when both the nesting and state integers 
hold a zero, it means that temporary compilation of a program 
control structure has just started. In this situation, nest 
will save the address of the start of the temporary compiled code 
in the bound system integer and then will compile the 2 byte 
machine code instruction which tells the system to 'jump to the 
nesting routine* (during program execution) at the start of the 
temporary code (please do not confuse the nesting system 
integer used by the program control structures with the nesting 
routine used during the execution of token threaded code) . 



- 131 - 



: nest ( - ) 

nesting state or 0= 

if 



here bound to 
4ED3 W, 



then 

1 nesting +to ; 



check the values of nesting ) 
and state ) 

if both nesting and state are ) 
0, we are starting the compilation 
of a control structure which is to 
be executed interactively ) 
save away the address of the ) 
start of the interactive code ) 
lay down a 'jump to the nesting ) 
routine* instruction at the start 
of the interactive code ) 

always increment the contents of ) 
the nesting system integer ) 



unnest 



unnest is the complement of the word nest : 



) 



unnest ( 

local oldhere 

local size 

-1 nesting +to 

nesting state or 

if 



nesting value ) 



( decrement the 
0= 

if the contents of nesting have ) 
been reduced to zero and the ) 
system is in the interpretation ) 
state, it's time to execute the ) 
temporary control structure code ) 
[compile] exit 
bound oldhere to { get the address of the start of ) 

( the temporary code ) 
here oldhere - size to 



oldhere execbuf size cmove 



oldhere here to 



execbuf 



size execbuf +to 



goto 



size negate execbuf 



( determine the size ) 

( of the temporary ) 

( code ) 

( move the code to ) 

( the execution ) 

( buffer ) 
move the here pointer back so ) 
the temporary code will be ) 
overwritten in the dictionary ) 
get the address of the execution ) 
buffer ) 

temporarily move the start of the 
execution buffer to the location ) 
just past the current temporary ) 
code ) 

execute the code at the execbuf ) 
address, the temporary code ) 
+to ( set the start address of ) 
the execution buffer back to its ) 
original address ) 



then 
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unnest will always decrement the contents of the nesting system 
integer. Then, if nesting has been reduced to zero and state 
holds a zero, the code between the if and the then in 
unnest will see to it that the temporary code is executed. Note 
that after the code has been copied up to the execution buffer 
the here pointer is moved back to the position it held before 
the start of the temporary compilation process. This ensures 
that the code area does not become cluttered with unused code. 



goto is used by unnest to directly execute the code located 
starting at the execution buffer address: 



goto { a - ) 

['] temp + table ! 



temp 



borrow temp's token table entry } 
put the address of the code to ) 
be executed in its token table ) 
field ) 
now execute temp ) 



The code which temp points to must end with a next in order to 
properly terminate execution. 

Compilation of Program Control Structures 

The if... then Control Structure 

Here is the definition of the word if : 



: if ( - a n ) 
nest 

compile <Obran> 
here 

c, 
2 ; 

immediate 



add one to the nesting level ) 
compile the <Obran> token ) 
return the address where <Obran> * s ) 
branch data should be located ) 
reserve a spot for <Obran> ' s data ) 
2 means 'if... then' structure ) 
immediate means if is executed ) 
at compile time ) 



if increments nesting , compiles the token for <0bran> , and 
compiles a byte length zero spacer in the location where 
<Obran>'s data will later be placed, if leaves the address of 
the <Obran> data location and a 2 on the parameter stack during 
compilation. The 2 indicates that the next piece of data on the 
parameter stack belongs to an 'if... then' control structure. 

else is used to mark the end of the if code and the start of 
the else code in an ' if .. .else. . .then* program control 
structure, else has three compile time duties. First it must 
verify that if was used previously. To perform this function 
else searches through the parameters on the stack. If it 
encounters a ' V , which identifies while or leave data, it 
moves both the identifier and the associated data over to the 
return stack. As soon as else has removed all while or 
leave data from the parameter stack it expects to find the '2' 
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which identifies if data. If else does not find the '2 1 'if 
data identifier at this point, a program control structures pair 
mismatch has occurred and the system will abort. 

Once else has found the if identifier it can perform its 
remaining two duties. First, else must compile an 
unconditional branching primitive (<bran>) and a byte-length '0* 
branch data spacer at the end of the if code. At execution 
time, this unconditional branch will terminate execution of the 
if code by routing execution past the else code to the code 
which immediately follows the then (see the previous diagram 
for pcs3). Next, else must calculate and backpatch the branch 
data for if so that the if branch points to the start of the 
else code. Because else did find the '2' on the stack, it 
knows that the next address on the stack is the if data, the 
address where the if branching data should be stored, else 
uses back to calculate the distance between this data location 
and the start of the else code and to insert the delta branch 
distance into the <0bran> data spot: 



back ( a - ) 
here over 
dup -80 7F inrange not 

abort" use long branch" 
swap c ! ; 



calculate delta distance ) 
make sure data is in the byte 
range ) 

abort if delta is too large ) 
store delta in correct spot ) 



else's final actions are to leave the address of its branch data 
location and a '2' 'if . .else. . then' control structure identifier 
on the parameter stack, and then to transfer any data left on the 
return stack back to the parameter stack. Here is the definition 
of else : 



else ( a n - 
>r 
begin 

dup 4 
while 

>r >r 
again 



) 



( put a marker on the return stack ) 
( move all the leave and while ) 
( data from the parameter stack ) 
( to the return stack ) 



"pairs 



compile <bran> 



back 
here 

begin 

while 

again 



1- 2 



r> ?dup 



r> 



{ was there an if which matches ) 

( this else? ) 
c, ( compile an unconditional branch ) 
( and a byte length spacer ) 
( backpatch the previous if data ) 
( leave the address of the else ) 
( data and the 'if... then' identifier ) 

( move all of the leave and while ) 
( data back to the parameter stack ) 



immediate 
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then is a simpler version of else . then is only responsible for 
checking for a previous if or else and backfilling the delta 
branch data for the previous if or else . then will also use 
back to take the data address left on the stack by if or else and 
to calculate the delta branch distance. If an else was used 
last, back will fill in the data for the <bran> token. If an if 
was used last, back will fill in the data for the <Obran> token. 
Since then closes the 'if... then* and 'if .. .else. . .then' 
program control structures, it uses urines t : 

: then (an-) 

>r ( put a marker on the return stack ) 

begin 

dup 4 = ( move all of the leave and while data ) 
while ( from the parameter stack to the return ) 

r> r> ( stack ) 
again 

2 ?pairs { check for an 'if .. .else. . .then* pair match ) 

back { backpatch the previous if or else ) 

{ branching data ) 
begin 

r> ?dup ( move all of the leave and while data ) 

while { back to the return stack ) 

r> 
again 

unnest ; (we've just closed a program control ) 

immediate ( structure so unnest... ) 

The do... loop Control Structure 

Return Stack Usage 

During the compilation of colon definitions, the system integer 
loops is used to keep track of the 'do... loop* return stack 
usage for the definition. Whenever a 'do... loop' is started, 12 
decimal is added to the contents of loops (each 'do.. loop' uses 
12 bytes of return stack space during execution: 4 for the 
'do... loop' start address, 4 for the limit value, and 4 for the 
loop count value). Whenever a 'do... loop' is terminated, 12 
decimal is subtracted from the contents of loops . 

The 'do... loop' return stack usage is monitored because two other 
words, doloc and exit are very return-stack-usage dependent, 
doloc , described previously, is the word responsible for 
compiling references to local variables. Local variable storage 
space is kept on the return stack and is located using an offset 
from the current top of the return stack. 

Although each local variable "tells" doloc what its storage 
location offset into the return stack should be, doloc will 
check the contents of loops to determine if the offset needs to 
be adjusted to account for extra 'do... loop' data which will be 
on the return stack (see the listing for doloc in the technical 
local variable discussion) at execution time. 
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exit is a word which may be used at any time to unconditionally 
terminate execution of the current colon definition. If the 
colon definition uses local variables or 'do. . .loops* , exit is 
responsible for proper clean-up of the return stack so that the 
return information required upon exit from the definition may be 
accessed. 



exit ( 
locals 

?dup 
if 



) 
loops + 



else 



then 



compile 



c, 



( does this word use the return ) 
( stack? ) 



{ if it does, compile a special form ) 
<exitlp> ( of exit which knows how to ) 
( clean up the return stack ) 
( compile the number of return ) 
{ stack bytes which are used by ) 
{ this word ) 



compile <exit> ( otherwise, compile the normal ) 



immediate 



( exit ) 



do, loop, and +loop 

The word do performs four compile time actions. First, since it 
is a word which starts a new program control structure, it uses 
the word nest . Second, since it requires 12 decimal bytes of 
return stack storage space, it increments the contents of loops 
by 12. Next, it compiles the token for <do> . Finally, it 
places the contents of the nestype system integer on the 
parameter stack, places the 'do... loop' identifier, '3', on the 
parameter stack, and places a '-!' in nestype 

nestype is a system integer which holds a value which 
distinquishes between 'do... loops' (-1) and 'begin' loops (0). 
Since 'do... loops' and 'begin' loops perform many similar compile 
time activities, tForth conserves code space by sharing compiling 
words between the two control structures. Since the shared words 
must still perform some loop-specific actions, the nestype 
integer is used to indicate which type of loop is currently being 
compiled. 

loop and +loop 

{loop} is used by all program control words which terminate 
program control structures ( loop , +loop , again , until 
). {loop} is passed two parameters, the structure identifier 
value for the type of structure being compiled (3 for 
'do... loops' and 1 for 'begin' loops), and the token for the 
control structure primitive compiled by the word which called 
{loop} (loop compiles <loop> , +loop compiles <+loop> , 
again compiles <bran> , until compiles <0bran> ) . The 
structure identifier value is stored in the system integer 
tempO . The token value is stored in the system integer tempi 
(because the program control structures compiling words make 
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p ( 


nl n2 n3 


nk 


tempO 


to 




tempi 


to 




>r 






begin 


dup 4 = 




while 


swap 
>r >r 




again 






tempi 


?pairs 




tempO 


c, 





extensive use of the return stack they cannot use local 
variables). The main actions of both loop and +loop are 
performed by the shared compiling word {loop} as follows: 



- ) 
get the token from the stack ) 
get the identifier from the stack ) 
put a marker on the return stack ) 

move all of the leave and while ) 
data to the return stack ) 
swap the data during transfer so ) 
that the identifier is on top of the 
address ) 

check for a pair mismatch ) 
compile the token for this type ) 
of looping structure ) 
( again compiles a <bran> ... ) 
{ until compiles a <0bran> ... ) 
is this an again or until? ) 
if it is, fill in the required ) 
branch data ) 



restore the previous nestype ) 
value, left on the stack by either ) 
do or begin ) 

is there any leave or while ) 
data on the return stack? ) 
if there is, calculate and backfill ) 
the leave or while branching ) 
data ) 



tempO ['] <bran> = 
tempi [ ' ] <0bran> 



or 



if 



then 



here 



c, 



nestype to 



begin 



while 



again 



r> 

here r@ 
r> c! 



After {loop} moves all leave and while data to the parameter 
stack it compares the structure identifier passed in on the 
parameter stack to the structure identifier stored in tempO to 
see if a pair mismatch has occurred. If all control structures 
are matched up properly {loop} will compile the token held in 
tempi and, if the token compiled was the token for <bran> or 
<Obran> , the delta branch data will be calculated and compiled. 
Next, the loop type is restored by storing the loop type value 
left on the stack by a previous do or begin into nestype . 

The final action of {loop} involves backfilling the delta 
branch data information for all unresolved leave and while 
tokens. Both leave and while compile branches to a location 
just outside of the current program control structure. Since 
this location cannot be determined until the program control 
structure has been closed, {loop} , which is only called by 
words which close program control structures, is used to perform 
this function. 
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begin , again . until 

begin is a much simpler version of do: 
: begin (-an) 



nest 
here 1 

nestype to 
immediate 



indicate that a new program control ) 

structure is being compiled ) 

leave the address of the start of the ) 

'begin' loop code and a 'begin' loop ) 

identifier ) 

store the 'begin* loop type identifier ) 

into nestype ) 



begin calls nest , leaves the address of the start of the 'begin' 
loop and a '1' to identify the 'begin* data, and sets nestype 
to '0' (identifies 'begin' type loops). 

again and until are also very straightforward control structure 
operators, again always takes an unconditional branch back to 

the start of the loop: 

: again ( n a - ) 

1 ( pass the 'begin' structure identifier ... ) 

[ ' ] <bran> ( and the token for the primitive compiled ) 
( by again ) 

{loop} ( ...to {loop} ) 

unnest ( this is the end of the structure so unnest ) 
; immediate 

again expects the 'begin' structure identifier and the address of 
the start of the 'begin' loop to be somewhere on the parameter 
stack when it is called, again will pass an additional 'begin' 
structure identifier, '1', and the token for the unconditional 
branching primitive <bran> to {loop} . {loop} will compile 
the <bran> token, and calculate and compile the delta distance 
between the <bran> token and the start of the 'begin' loop. 

The only difference between until and again is that until 
causes a conditional branch to the start of the loop to be 
compiled: 

: until ( n a - ) 
1 

[»] <Obran> 
{loop} 
unnest ; 

while and leave 

while and leave are used to conditionally or unconditionally exit 
from the current loop control structure: 

: while ( - ) 

[ ' ] <0bran> ( while compiles <0bran> if it is used ) 
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[ ' ] <01eave> 

{while} 
immediate 



( inside of a 'begin' loop ) 

( while compiles <01eave> if it is used 

( inside of a 'do' loop ) 

( {while} makes the decision ) 



: leave { - ) 
[ ' ] <bran> 

[ ' ] <leave> 

{while} 
; immediate 
: {while} { nl n2 

nestype 

if 

swap 

then 

drop 

c, 

here 4 



c, 



leave compiles <bran> if it is used ) 

inside of a 'begin* loop ) 

leave compiles <leave> if it is used ) 

inside of a 'do* loop ) 

{while} makes the decision ) 

- ) 

is this a 'begin' loop or a 'do' loop? ) 

if its a 'do* loop, dispose of the second ) 

token on the stack, the second token ) 

is the token to be used inside of 'begin* ) 

loops ) 

compile the remaining token ) 

leave the address of the branching data ) 

for the compiled branching primitive and ) 

leave a while / leave data identifier ) 

compile a byte length spacer for the ) 

while or leave data ) 



If while or leave are used inside of a 'begin' loop either a 
conditional or unconditional branch out of the loop will be 
compiled. If while or leave are used inside of a 'do' loop a 
conditional or unconditional branch out of the loop with return 
stack clean up will be compiled. The word {loop} , described 
above, is used to backfill the branching data for while and leave 

Some Notes on Initial Program Control Structures 

Any number of tForth control structures may be nested within a 
program control structure. The program control structures 
described only support branches up to 256 bytes in length (short 
branches). They are currently being modified to support branches 
which are up to 32K bytes in length {word branches). See below. 

Program Control Structures Which Support Byte and Word Length 
Branching 

These 13 words are used to implement the new program control 
structures: 



if backelse {else then} else then 



{while2} 
{loop2} 



while 
until 



leave 
again 



loop +loop 
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if .. .else. . .then Control Structure Words 

Only the ' if .. .else. .. then' program control words can cause code 
movement to occur. The word if will always leave a single byte 
spacer for its associated data. If else or then later 
determine that the code between the if and the else , or 
between the if and the then take up more than 7F hex bytes, 
the if data space will have to be expanded to word length. The 
code between the if and else or between the else and then 
will have to shifted one byte towards higher memory, if 
temporarily stores the byte length hexadecimal code FF in its 
data area during compilation. This code is used to inform else 
and then that the data are belongs to an if. 

The new version of if is very similar to the previous version. 
The only difference is that the new version leaves a hex FF, 
rather than a 0, in its byte length data area. 

else always leaves a 2-byte spacer for its associated data, else 
temporarily stores the offset back to the if data in this 2-byte 
space during compilation. If the offset back to the if data area 
is short, the first byte in the else data area will be the 
hexidecimal code FE and the second byte will be the byte length 
offset. If the if offset is long, greater than 7F hex bytes, the 
entire word offset is stored in the else data area. If else 
determines that the offset back to the if data is greater than 
hex 7F bytes, it will shift the code between the if and else by 
one byte to make room for 2 bytes of if data, store the word 
length delta branching distance in the enlarged if data area, and 
will change the <0bran> instruction compiled by if to a <0branl> 
instruction. 

If then is used after if , with no intermediate else , then 
performs functions which are very similar to else . If the 
distance between the if and the then is less than 7F hex bytes, 
then will simply store the delta distance in the if data area. 
If the distance is greater than 7F hex bytes, then will shift the 
code between the if and the then up in memory by one byte, store 
the word length delta branching distance in the if data area, and 
will replace the <0bran> token with the token for <0branl>. 

If then is used after else it will first calculate the distance 
between the start of the else data area and the then destination 
point. If this distance is short, then will store the byte 
length branching distance in the first byte of the two byte else 
data area and then will move the code between the else and the 
then down in memory by one byte to recover the second unused byte 
of the else data area. Before performing this code movement, 
then will snake back up to the if data area, using the offset 
stored temporarily in the else data area, and reduce the if 
branching distance by one byte (since the start of the else code 
is to be moved down in memory by one byte) . If the distance 
between the else and then is long, then will store the word 
length delta branching distance directly in the word length else 
data area and will change the <bran> token to a <branl> token. 
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(else then} 

Since else and then perform many similar functions, a common 
lower level word {elsethen} has been defined to conserve program 
space, {elsethen} performs three major actions. First, it 
transfers all of the leave and while data to the return stack. 
Next, it takes care of all if or else backpatching and code 
movement. Finally, it takes the leave and while data off of the 
return stack and adjusts the addresses as necessary. The 
backpatching code will return a '+1' value if the code had to be 
moved towards higher memory, a ' -l 1 if the code had to be moved 
towards lower memory, or a '0' if the code was not moved. 
{elsethen} will use this value when it adjusts the leave and 
while addresses, {elsethen} is passed a flag which tells it which 
conditional word, else or then „ is using it. 

backelse 

backelse is a word used by {elsethen} when backpatching else data 
is required. 

begin and do Loop Structures 

The words begin , again , until , loop , and +loop have only been 
modified so that they use the newer versions of the words 
{while} and {loop}. 

while and leave now always use a 2-byte branching distance, 
until and again will use either a byte or 2 byte branching 
distance. 

Size Considerations 

There are currently approximately 160 uses of while and 20 uses 
of leave in the Cat code. Use of these new program control 
structures will cause these words to use 3 bytes of code space 
each rather than the 2 bytes of code space they each used 
previously so the code space will increase by 180 bytes. 

The code used to implement these new versions of the control 
structures is 280 bytes larger than the older control structures 
code . 

Therefore, these modifications will cause the Cat program to take 
up 480 more bytes of program space. 
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THE tFORTH 68000 ASSEMBLER 



INTRODUCTION 

This section of the manual will explain the syntax and usage of 
the tForth 68000 assembler. The architecture, addressing modes, 
and instruction set of the 68000 microprocessor will be discussed 
briefly. For more detailed information on the 68000 
microprocessor please refer to the Motorola Microprocessor 
Reference Manual, 4th Edition. 

Any differences between the standard Motorola-format 68000 
assembler syntax, as presented in the examples in the Motorola 
Microprocessor Reference Manual , hereafter referred to as the 
M68000 manual, and the syntax required by the tForth assembler 
will be noted in the text. 



142 



BRIEF OVERVIEW OF THE 68000 MICROPROCESSOR 

Internally, the 68000 has 32-bit data and address paths. 
Externally the 68000 has 16 data lines and 2k address lines. The 
2k external address lines allow the 68000 microprocessor to 
directly access 16 megabytes of address space. 

Execution Environment 

The 68000 executes in one of two 'modes': user mode and 
supervisor mode. "Cat" code always executes in supervisor mode. 
In user mode a program is only allowed to execute a subset of the 
available 68000 program instructions. The prohibited 
instructions are those which are usually used by systems level 
software. 

The diagram on the following page shows that eight 32-bit data 
registers, eight 32-bit address registers, a 32-bit stack 
pointer, a 32-bit program counter, and a 8-bit condition code 
register are available during user mode program execution. 

In supervisor mode the 32-bit supervisor stack pointer and the 
16-bit status register (an extension of the 8-bit condition code 
register) are also available. 

Data Registers 

Each data register supports data operands of 1, 8, 16, or 32 
bits. Byte operands occupy the low order 8 bits, word operands 
the low order 16 bits, and long word operands the entire 32 
bits. The least significant bit is addressed as bit zero; the 
most significant bit is addressed as bit 31* When a data 
register is used as either a source or destination operand, only 
the appropriate low order portion is changed; the remaining 
high-order portion is neither used nor changed (i.e. if a data 
register is used to hold a byte sized operand, only the lower 8 
bits of the data register are affected by the operation) . 

Address Registers 

All address registers and both stack pointers are 32 bits wide 
and hold full 32 bit addresses. Address registers do not support 
byte sized operands. Therefore, when an address register is used 
as a source operand, either the low order word or the entire long 
word operand is used depending upon the operation size. When an 
address register is used as the destination operand, the entire 
register is affected regardless of the operation size. 
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68000 Execution Environment 
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THE 68000 INSTRUCTION SET 

The 68000 instruction set allows the following eight types of 
operations to be performed: 



OPERATION 
Data Movement 



Integer Arithmetic 



Logical 



Shift and Rotate 



Bit Manipulation 



INSTRUCTION (tFORTH ASSEMBLER) 



exg, 


lea, 


link, 


unlk, 


movem , 


movep , 


moveq, 


move, 


pea, 


swap , - 






add, 


addx, 


addi, 


addq, 


clr, 


cmp. 


cmpa, 


divs, 


divu, 


ext , 


muls, 


mulu, 


neg, 


negx, 


sub, 


subi, 


subq, 


subx, 


tas, 


tst, 




and, 


andi. 


or, 


ori, 


eor, 


eori, 


not, 






asr , 


asl, 


lsr, 


lsl, 


roxr, 


roxl, 


ror, 


ror, 




bchg, 


bclr, 


bset, 


btst. 







Binary Coded Decimal abed, 



sbed, 



nbed, 



Program Control 



System Control 



bra, 


bsr, 


dbra, 


jmp, 


jsr, 


rtd, 


rtr, 


rts, 


set, 


rte, 


reset, 


stop, 


trapv, 


chk. 


trap, 



Note: The 68000 instruction names used in the tForth assembler 
are very similar to those presented in the M68000 manual. The 
only differences are that in the tForth assembler the instruction 
names must be written in lowercase and must be immediately 
followed by a comma. 
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USING THE tFORTH ASSEMBLER 

tForth Assembler Syntax 

The tForth assembler, unlike the Motorola assembler, uses a 
postfix syntax. This means the operands precede the instructions, 



sp ) + dO 
<operands> 

(or, more specifically) 



. 1 move , 
<instruction> 



sp )+ dO .1 move, 

<source> <destination> <instruction> 

the register/data specifications precede the address mode 
specification, 

sp ) + 

<register/data specification <address mode specification 

and the instruction size precedes the instruction: 



.1 
<size> 



move, 

< ins true tion> 



Code Definitions 

In most FORTH implementations, a FORTH definition is composed of 
intermediate threading information (FORTH instructions) instead 
of directly executable machine code instructions. The term 'code 
definition' is used to refer to those definitions which consist 
of machine code instructions. 

The word code is used to create named tForth assembly 
definitions, code (i) creates a name in the dictionary for <name> 
(so that the code definition can be found in the future), (ii) 
tells the system that all subsequent words should be compiled 
rather than executed, (iii) and puts the assembler vocabulary 
asm68 (the vocabulary which contains all of the assembler 
instructions) first in the search order. 

Here is an example of a tForth code definition: 



code swap ( nl n2 - n2 nl 

sp ) + dO move , 

sp ) + dl move , 

dO sp -) move, 

dl sp -) move, 

next; 



| Swaps the top two stack items. 

take n2 off of the stack and put ) 

it in the dO register ) 

take nl off of the stack and put 

it in the dl register } 

put the contents of the dO ) 

register on the stack ) 

put the contents of the dl ) 

register on the stack ) 

end this assembly routine ) 
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The standard formats for a code definition are: 



next; 



code 


<name> 


• ... 


next; 


code 


<name> 


next , 


next , 


code 


<name> 


. ;c 




code 


<name> 


next, 


next , 


The word next; 


[ 'next -semi -colon' ) i 



;c 



the code definition which during execution will (i) help the 
interpreter switch between the execution of machine language 
instructions and the exection of FORTH instructions, (ii) check 
the return stack to make sure it has not been corrupted, and 
(iii) remove asm68 from the search order, next; and next, 
{'next-comma', described below) are used in code definitions that 
are called from FORTH and return to FORTH when they terminate 
execution. 

The word next, is used when more than one exit from a code 
definition is required, next, is similar to next; in that it 
also inserts a 'return to FORTH' instruction into the code 
definition being constructed, next, does not check the return 
stack or remove the assembler vocabulary from the search order. 

The word ;c { 'semi-colon-c' ) is used in code definitions which 
do not exit at the end or in code definitions which should not 
return to FORTH after execution of the code definition terminates 
(perhaps a code definition which is called from another code 
definition instead of called from FORTH). ;c (i) checks the 
return stack and (ii) removes the assembler vocabulary from the 
search order. The word next; is defined: 

: next; ( - ) 

next, ( compile an 'exit to FORTH' instruction ) 

;c ; ( check the stack and deactivate asm68 ) 

Creating Unnamed Assembly Code Fragments 

The tForth assembler also includes provisions for the creation of 
assembly language code fragments. A code fragment is an assembly 
language routine which has no dictionary entry, and thus cannot 
be referenced by name. A common format for the use of code 
fragments is shown below: 

frag <integername> to ... c; 

frag puts the address where the first instruction in the code fragment 
will be located on the stack. The sequence * <integername> to', although 
not required, is usually used to save the address of the code fragment 
away for future reference, c; is used to terminate a code fragment. 

Note: A tForth code definition (a set of assembly language 
instructions) must always be preceded by either code or .frag 
and must always be followed by either next; or ;c 
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SPECIFYING ASSEMBLER OPERANDS 

A complete assembler instruction consists of a 68000 assembly 
instruction and the source and/or destination operand on which 
the instruction will operate. A complete assembler source or 
destination operand consists of a register or data specification 
and an addressing mode specification. 

Register Specification 

The following symbols are used in source and destination operands 
for register specification in both the tForth assembler and in 
the M68000 manual: 

SYMBOL MEANING 

an Address register, ' n' specifies the register number 

dn Data register, 'n' specifies the register number 

rn Address or data register, ' n' specifies register # 

pc Program counter 

sr Status register 

ccr Condition code half of status register 

sp Active stack pointer (user or supervisor) 

usp User stack pointer 

ssp Supervisor stack pointer 

d8 8 bit displacement (-80... 7F hex) 

dl6 16 bit displacement (-8000. . .7FFF hex) 

d32 32 bit displacement (-8000000. . .7FFFFFFF hex) 

xxxx Number, size determined by instruction size. 

addrl6 16 bit address. 

addr32 32 bit address. 

SPECIAL NOTE: During execution, tForth uses certain 68000 
registers for special purposes. For code readability, the 
following registers have been assigned special symbols which are 
recognized by the tForthassembler (the usage of these registers 
is explained in more detail in the compilation discussion 
included in the technical reference section of this manual): 

REGISTER SYMBOL CONTENTS 

Address of the base of the token table. 

Address of the value of the current integer. 

Zeroth nesting starting address. 

Address of the current token. 

Parameter stack pointer. 

Return stack pointer. 

Interpretation pointer. 

Next pointer. 

Nest pointer. 

Pointer to the code for integer 



d7 


bp 


d6 


iv 


d5 


sa 


d4 


ct 


a7 


sp 


a6 


rp 


a5 


ip 


a4 


nx 


a3 


np 


a2 


vp 
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In the swap code definition presented at the start of this 
discussion the symbols 'dO' and ' dl* were used to specify data 
register zero and data register one and the symbol ' sp' was used 
to specify the stack pointer (the parameter stack pointer in 
tForth) . 

Address Modes 

Address modes are used to specify the location of instruction 
operands or data to the microprocessor. The 68000 supports 12 
address modes. The table below lists each of the 12 address 
modes and the Motorola and tForth assembler syntax used for each 
address mode: 



MOTOROLA SYNTAX tFORTH SYNTAX 



DESCRIPTION 



1. Dn 

2. An 
3- (An) 
4. (An)+ 

5- "(An) 

6. dl6(An) 

7. d8(An,Rn.W) 
d8(An,Rn.L) 

8 . xxx . W 
9 • xxx . L 

10. dl6(PC) 

11. dl6(PC,Rn.W) 

dl6(PC,Rn.L) 

12 . #xxxx 



dn 
an 

an ) 
an ) + 

an -) 

an dl6 )d 

an rn . w d8 
an rn . 1 d8 
addrl6 
addr32 
dl6 pc)d 



rn.w dl6 
rn.l dl6 
xxxx #n 



xw)d 
xl)d 



pc,xw)d 
pc,xl)d 



Data register direct. 
Address register direct. 
Address register indirect. 
Address register indirect 
with postincrement. 
Address register indirect 
with predecrement. 
Address register indirect 
with displacement. 
Address register indirect 
with index. 

Absolute short address. 
Absolute long address. 
Program counter with 
displacement. 
Program counter with index 

Immediate data. 



Examples 

Since the 68000 'move' instruction allows its source operand to 
be specified with the use of any of the address modes listed 
above, it is a good instruction to use when providing examples of 
the usage of the address modes (the source operand is the 
leftmost operand in the tForth assembler syntax) : 



Address 
Address 
Address 
Address 
Address 
Address 
Address 
Address 
Address 
Address 
Address 
Address 



mode #1 
mode #2 
mode #3 
mode #4 
mode #5 
mode #6 
mode #7 
mode #8 
mode #9 
mode #10 
mode #11 
mode #12 



dO sp 

aO sp 

aO ) sp 

aO ) + sp 

aO - ) sp 

aO 4 )d sp 

aO d2 4 xw)d sp 

7ce0 sp 

420000 sp 

4e00 pc)d sp 

d4 7F8 pc ( xl)d sp 

400 #n sp 



.1 
.1 
.1 
.1 
.1 
.1 
.1 
.1 
.1 
.1 
.1 
.1 



move, 
move, 
move, 
move, 
move, 
move, 
move, 
move, 
move, 
move, 
move, 
move, 
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Address modes 1 and 2 are 'register direct addressing modes'. 
These addressing modes are used when the operand is in either an 
address or data register. 

Address modes 3 through 7 are 'memory address modes'. These 
address modes are used when the operand is located somewhere in 
memory. These address modes are evaluated to produce the address 
in memory where the operand is located. 

Address modes 8 and 9 are used when the address of the operand is 
specified explicitly to the instruction. 

Address modes 10 and 11 are special versions of the 'memory 
address modes'. Although they function similarly to address 
modes 6 and 7t they are put in a special class because it is 
assumed that these addressing modes will be used to access 
locations in the program code area rather than in the program 
data area. 

Address mode 12 is used when the operand is specified explicitly 
to the instruction. 

For more detailed information on how address modes are evaluated, 
please refer to the 'Program/Data References' (section 2.7) of 
the M68000 manual. 

Address Mode Categories 

Certain 68000 instructions can only use a subset of the available 
addressing modes. On the individual instruction glossary pages 
in the M68000 manual, the following classifications are used to 
categorize the addressing modes which a particular instruction 
may use: 

1. DATA ADDRESSING ADDRESS MODES 

If an effective address mode may be used to refer to 
data operands, it is considered a data addressing 
effective address mode. 

an ) 
an -) 

an rn.w d8 xw)d 
xl)d addrl6 

dl6 pc)d 
pc,xw)d rn.l dl6 pc,xl)d 



dn 






an 


)♦ 




an 


dl6 


)d 


an 


rn.l 


d8 


add 


r32 




rn. 


w dl6 


P 1 


xxxx #n 
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2. MEMORY ADDRESSING ADDRESS MODES 

If an effective address mode may be used to refer to 
memory operands, it is considered a memory addressing 
effective address mode. 



an ) 
an -) 
an rn.w 
addrl6 
dl6 pc)d 
rn.l dl6 



d8 xw)d 



pc,xl)d 



an ) + 
an dl6 
an rn.l 
addr32 
rn.w dl6 
xxxx #n 



)d 
d8 



xl)d 



pc,xw)d 



3. ALTERABLE ADDRESSING ADDRESS MODES 

If an effective address mode may be used to refer to 
alterable (writable) operands, it is considered an 
alterable addressing effective address mode. 



dn 

an ) 
an -) 
an rn.w 
addrl6 



d8 xw)d 



an 




an ) + 




an dl6 


)d 


an rn.l 


d8 


addr32 





xl)d 



4. CONTROL ADDRESSING ADDRESS MODES 

If an effective address mode may be used to refer to 
memory operands without an associated size, it is 
considered a control addressing effective address mode 



an ) 
an rn.w 
addrl6 
dl6 pc)d 
rn.l dl6 



d8 xw)d 



pc,l)d 



an dl6 ] 
an rn.l 
addr32 
rn.w dl6 



d 
d8 



xl)d 
pc,xw)d 



Operand Size 

The size of the operand to be used by a 68000 instruction can be 
specified with the use of the assembler words .b , .w , and 
.1 . .b means the source and destination operands are 1 byte 
in size. ,w means the source and destination operands are 2 
bytes in size. .1 means the source and destination operands are 
4 bytes in size. If no operation size is specified, the 
assembler assumes the operands are 4 bytes in size. 

HOW OPERAND SIZE AFFECTS REGISTER OPERATIONS 



dO dl .b move, 

dO dl .w move, 

dO dl .1 move, 

dO dl move, 



Move the lowest order byte of ) 

register dO to register dl . ) 

Move the lowest order word of ) 

register dO to dl. ) 

Move the entire 4 bytes in register dO 

to register dl. ) 

Same as ' . 1 move , * . ) 
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How Operand Size Affects Memory Operations 



al ) dl .b move. 



al ) dl .w move, 



al ) dl .1 move, 



Move the byte of data located at ) 
address al into the lowest order ) 
byte of register dl. ) 

Move two bytes of data into register dl. 
The byte at address al goes into the ) 
second lowest order byte in dl and the ) 
byte a address al+1 goes into the lowest 
order byte of dl. ) 

Move the four bytes located in memory ) 
starting at address al into the dl ) 
register. The byte at al goes into the 
highest order byte of dl and the byte ) 
at address al+3 goes into the lowest ) 
order byte of dl . ) 
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STRUCTURED ASSEMBLY LANGUAGE PROGRAMMING SUPPORT 

The tForth assembler allows special versions of the conditional 
and indefinite looping high-level FORTH program control 
structures to be included in assembly language code definitions. 
The assembler versions of the program control structures make 
decisions based on the microprocessor condition code state. 

The Condition Code Register 

The 'condition code register' (ccr), which is located in the 
lower order byte of the status register {see diagram on the 
following page) , holds the condition code information. The 5 
bits which represent the five possible condition codes (negative, 
zero, overflow, carry, and extend} are also shown. Certain 68000 
instructions modify the condition codes to reflect the outcome of 
their operation. The condition codes can be combined, or used 
individually, to perform the following conditional tests: 

tFORTH CONDITION CODE SYMBOL CONDITIONAL TEST 

tr always true 

nt always not true or false 

hi high 

Is low or same 

nc carry clear, no carry 

cs carry set 

ne not equal 

eq equal 

nv overflow clear, no overflow 

vs overflow set 

pi plus 

mi minus 

ge greater or equal 

It less than 

gt greater than 

le less or equal 
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Status Register 



*4 System Byi 



User Byte ► 



15 13 



10 8 



t(^s^^1i2|ii|io|S^^v]x|n|z|v|c 



Trace Mode 



Supervisor 
State 



Interrupt 
Mask 



Condition 
Codes: 



Extend 

Negative 

Zero 

Overflow 

Carry 



Using Conditional Test Structures in Assembly Language Words 

The 'if .. .else. . .then* conditional program control structure has 
the following format when used in code definitions: 



cc if, 
cc if, 



then, 
else 



then, 



The 'cc' is used to denote a condition code symbol. The word @ 
, which is used to fetch a four byte value from a memory 
address, is a tForth code definition which uses the 'if , . . . then, * 
assembly language program control structure: 



code @ ( a 


- n ) 


sp ) aO 


move 


aO dO 


.w move 



1 #n dO .b lsr, 



cs if, 



aO ) + 


sp 


) 




aO ) + 


sp 


1 


)d 


aO ) + 


sp 


2 


)d 


aO ) + 


sp 


3 


)d 


next, 








then, 









aO ) sp ) 



next; 



put address in the aO register ) 
move the lower word of the address ) 
into the dO register ) 

shift the least significant bit out of ) 
the dO register and into the condition ) 
code 'carry' bit ) 

IF the bit was a * 1', the address was ) 
odd so the long word must be fetched ) 
one byte at a time) 
.b move, { if the condition was met ) 
.b move, { these instructions will be ) 
.b move, { executed. ) 
.b move, 

{ intermediate exit to FORTH ) 
( if the condition was not met above ) 
( the next instruction will be executed ) 
move, { move 4 bytes at once since data is on ) 
( even byte address ) 
( check return stack, deactivate ) 
( asm68 , and exit to FORTH ) 



All of the FORTH comparison operators also use the 'if , . . . then, ' 
assembly language conditional program control structure. Here is 
the code definition for the word max : 



code 


max ( nl 


n2 


- n3 




sp ) + dO 




move, 




sp ) do 




cmp, 




gt if, 








dO sp 


) 


move, 




then, 







next; 



Compare nl to n2, return the greater. ) 

( get parameter 'n2' ) 

( subtract n2 - nl ) 

( IF the condition codes indicate that ) 

( n2 is greater than nl , put n2 in ) 

( the top stack position ) 

( otherwise, leave nl on top of stack ) 

( terminate code definition ) 
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Using Indefinite Loop Structures in Assembly Language Words 

The assembly language versions of the indefinite looping program 
control words are used as follows: 



begin ( 
begin, 

begin , 
begin , 

begin , 
begin , 



again , 

cc while, 

[ leave , ] 
cc while, 

[ leave , ] 
cc while, 



[ leave , ] 

cc until, 
[ leave , ] 



again , 



cc until, 



dn cc -until, 
[ leave, ] ... dn cc -until, 



The words in square brackets ( [ ] ) denote optional program 
control words which may be used. All of these constructs, except 
for the 'begin, .. .dn cc -until' construct, should be familiar, 
-until, is a special assembly language program control word 
which utilizes the 68000 'DBcc' (decrement and branch) 
instruction, -until, takes two inputs, a data register 
specification and a condition code specification. Each time 
through the loop, if the condition is NOT met, the contents of 
the specified data register will be decremented. A -until, 
loop will continue until either the count in the data register 
reaches -1, or until the condition is met. 

The tForth word fill uses a -until, loop: 



code fill 


( 


a n b 


- ) 


sp ) + 


dO 


move, 




sp ) + 


dl 


,w move, 




sp ) + 


d2 


.w move, 




sp ) + 


aO 


move, 







.b 


bra, 




begin , 








begin , 








dO 


aO ) + 


.b move 







:1 


( 



put fill char in the dO register ) 
put high word of count in dl register 
put low word of count in d2 register ) 
put address in aO register ) 
one-time branch down to the label '0' 
perform outer loop until the upper ) 
word of the count is reduced to -1 ) 
perform inner loop until the lower ) 
word of the count, in d2, is -1 ) 

create a label #0, discussed below ) 
d2 nt 
-until, 
dl nt 
-until, 
next ; 

fill code definition demonstrates that assembly language program 
control structures may be nested, fill used nested loops 
because the 'DBcc' instruction can only work with a 16 bit count 
value in the data register. The nested loops allow the user to 
pass a 32 bit count value to fill . Since the nt condition 
code always evaluates to false, the -until, loop never 
terminates due to the condition code. When the nt condition code 
is used in an -until, loop, the loop will only terminate when 
the count in the data register is reduced to -1. 
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Labels 

Ten local labels are allowed within a single code definition. 
Labels are defined using :1 : 



Labels are defined in the code definition at the spot which the 
label should mark. In the definition of fill above, a label 
was placed inside of the inner ' begin, .. .-until, ' loop. 

The number passed to :1 is used to identify the label. Label 
numbers must be between and 9* Three 68000 instructions may be 
passed label numbers: bra, , bsr, , and cc bra, : 

2 :1 d3 clr, ... 2 bra, { unconditional branch back to ) 

( the clr, instruction located at ) 
( label 2 ) 

2 :1 d3 clr, ... 2 eq, bra, ( conditional branch back to the ) 

( clr, instruction, branch only ) 
( occurs if the condition is met ) 

2 :1 d3 clr, ... 2 bsr, { unconditional branch to a ) 

( subroutine ) 

2 bra, ... 2 :1 d3 clr, ( forward and backward branching are) 

( allowed ) 
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THE movem, INSTRUCTION 

The 68000 mo vein, instruction is used to move multiple values to 
and from registers at once. For example, to move several 
registers onto the parameter stack: 

(regs d4 d5 d6 d7 a3 a4 a5 a6 to) sp -) movem, 

To restore the contents of the registers from the parameter stack 

{regs d4 d5 d6 d7 a3 a4 a5 a6 from) sp )+ movem, 
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tFORTH ASSEMBLER WORDS 



These are the available tForth assembler words 
in the asm68 vocabulary) : 



all are located 



#n 


(regs 


) 


)♦ 


)d 


") 


-until, 


.b 


.1 


.w 


:1 


;c 


aO 


al 


a2 


a3 


a** 


a5 


a6 


a7 


abed, 


add. 


adda, 


addi, 


addq, 


addx, 


again, 


and, 


andi, 


asl, 


asr, 


bchg, 


bclr, 


begin, 


bp, 


bra, 


bset. 


bsr, 


btst. 


ccr 


chk, 


clr, 


emp, 


empa, 


empi, 


empm, 


cs 


ct 


dO 


dl 


d2 


d3 


d4 


d5 


d6 


d7 


dbra, 


divs, 


divu, 


else, 


eor, 


eori , 


eq 


exg, 


ext, 


from) 


ge 


gt 


hi 


if. 


ip 


iv 


jmp, 


jsr, 


le 


lea 


leave , 


link, 


Is 


lsl, 


lsr, 


It 


mi 


move, 


movem, 


movep, 


moveq, 


muls, 


mulu, 


nbed, 


nc 


ne 


neg, 


negx, 


next, 


nop, 


not, 


np 


nt 


nv 


nx 


or, 


ori, 


pc)d 


pc , xl ) d 


pc , xw ) d 


pea, 


Pi 


reset, 


rol, 


ror, 


roxl, 


roxr, 


rp, 


rtd, 


rte, 


rtr, 


rts, 


sa 


sbed, 


set, 


sp, 


sr 


stop, 


sub, 


suba, 


subi, 


subq, 


subx, 


swap, 


tas, 


then, 


to) 


tr 


trap, 


trapv , 


tst, 


unlk, 


until, 


usp 


vp 


vs 


while, 


xl)d 


xw)d 
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GLOSSARY (tFORTH KERNEL WORDS ARRANGED BY FUNCTION) 

ARITHMETIC OPERATORS 

* ( nl n2 - n3 ) 

( * times ' ) 

Multiplies nl*n2 and leaves the 32-bit result on top of 
the stack. 

*/ ( nl n2 n3 - n4 ) 

( 1 times -divide* ) 

First, nl is multiplied by n2, leaving a 64-bit intermediate 
result on the stack. The intermediate result is then divided 
by n3, leaving the 32-bit quotient, n4, on the stack. The 64-bit 
intermediate result allows this operation to respond with 
greater precision than the equivalent sequence: nl n2 * n3 / . 

*/mod ( nl n2 n3 n4 n5 ) 
( 'times-divide-mod 1 ) 

First, nl is multiplied by n2, leaving a 64-bit intermediate 
result on the stack (the intermediate result occupies two 
stack positions). The intermediate result is then divided by 
n3, leaving the 32-bit remainder, n4, and the 32-bit quotient, n5, 
on the stack. 

+ ( nl n2 - n3 ) 

('plus') 
Adds nl plus n2 and leaves the 32-bit result on the stack. 

( nl n2 - n3 ) 

( ' minus ' ) 

Subtracts nl minus n2 and leaves the 32-bit result on the stack. 

-1 ( - -1 ) 

( 'minus-one 1 ) 

Puts the commonly used constant value '-1 1 on top of the 

parameter stack. 

/ ( nl n2 - n3 ) 

{'divide') 
Divides nl by n2 and leaves the 32-bit quotient on the stack. 

/mod { nl n2 - n3 n4 ) 
{ 'divide-mod' ) 

Divides nl by n2 and leaves the 32-bit remainder, n3, and the 
32-bit quotient, n4, on the stack. 

( - ) 
( ' zero' ) 

Puts the commonly used constant '0' on top of the parameter 
stack. 

1 ( - 1 ) 

Puts the commonly used constant '1' on top of the parameter 
stack. 
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1+ { nl - n2 ) 

( * one-plus ' ) 
Adds one to the number on top of the stack. 

1- ( nl - n2 ) 
{ • one-minus ' ) 

Subtracts one from the number on top of the stack. 

2* ( nl - n2 ) 

( ' two-times ' ) 
Multiplies the number on top of the stack by two. 

2+ { nl - n2 ) 

( ' two-plus ' ) 
Adds two to the number on top of the stack. 

2- ( nl - n2 ) 
( ' two-minus ' ) 

Subtracts two from the number on top of the stack. 

2/ ( nl - n2 ) 

( ' two-divide' ) 

Divides the number on top of the stack by two. 

abs ( n - lnl ) 
{ 'absolute' ) 
Returns the absolute value of the number on top of the stack. 

mod { nl n2 - n3 ) 

nl is divided by n2 and the 32-bit remainder, n3, is left on 
top of the stack. 

negate ( n - -n ) 

Returns the two's complement of n, i.e. n is subtracted 
from zero (0-n) . 

shl ( nl n2 - n3 ) 
('shift-left') 

Shifts the bits in 'nl* 'n2' bits to the left. Leaves the 32-bit 
result, 'n3' t on the parameter stack. 

shr { nl n2 - n3 ) 
('shift-right') 

Shifts the bits in 'nl' f n2' bits to the right. Leaves the 32-bit 
result, 'n3 1 , on top of the parameter stack. 

um* ( ul u2 - u3 ) 
( 'u-m- times' ) 

Multiplies the unsigned values ul*u2 and returns the 32-bit 
unsigned result, u3, on top of the stack. 
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um/mod ( ul u2 - u3 u4 ) 
{ ' u-m-divide-mod 1 ) 

The 32-bit unsigned value ul is divided by the 32-bit unsigned 
value u2. The 32-bit unsigned remainder, u3, and the 32-bit 
unsigned quotient, u4, are left on top of the stack. 
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LOGIC OPERATORS 



and 



( nl n2 - n3 ) 

Performs a bit-by-bit logical and using nl and n2. returns 
32-bit result (n3) on the parameter stack. The FORTH code 
definition for and is shown below: 



the 



code and 

sp 



( 
)♦ 



nl 
dO 



n.2 
move 



- n3 ) 



dO sp ) and 



next; 



take the 32-bit value [n2] off ) 
the top of the parameter stack ) 
and put in the dO register. ) 
perform an and operation. ) 
using the 32-bit value on top of ) 
the stack [nl] and the value in ) 
the dO register [n2] , replace ) 
the value on top of the stack ) 
with the result ) 
return ) 



not 



( nl - n2 ) 

Takes the ones complement of the 32-bit value on top of the 
parameter stack. Returns the 32-bit result on top of the 
parameter stack. The FORTH code definition for not is 
shown below: 



or 



code not ( 
sp ) 

next; 



nl 
not, 



n2 ) 



{ take the ones complement of ) 
( the 32-bit value on top of the ) 
( parameter stack. ) 
( return } 



( nl n2 - n3 ) 

Performs a bit-by-bit logical or using nl and n2. Returns the 
32-bit result (n3) on the parameter stack. The FORTH code 
definition for or is shown below: 



xor 



code or { nl n2 - n3 
sp )+ dO move, 



dO sp ) or, 



next; 



take the 32-bit value [n2] off ) 
the top of the parameter stack ) 
and put in the dO register. ) 
perform an or operation. ) 
using the 32-bit value on top of 
the stack [nl] and the value in ' 
the dO register [n2]. replace ) 
the value on top of the stack ) 
with the result ) 
return ) 



{ nl n2 - n3 ) 

Performs a bit-by-bit logical xor using nl and n2. Returns the 
32-bit result on the parameter stack. The FORTH code definition 
for xor is shown below: 
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code xor ( nl n2 - n3 ) 

sp )+ dO move, 



dO sp ) eor, 



next; 



take the 32-bit value [n2] off ) 
the top of the parameter stack ) 
and put in the dO register. ) 
perform an exclusive or operation 
using the 32-bit value on top of ] 
the stack [nl] and the value in ) 
the dO register [n2]. replace ) 
the value on top of the stack ) 
with the result ) 
return ) 
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COMPARISON OPERATORS 
0< 



0= 



<> 



inrange 



max 



mm 



u< 



( n - f ) 

{ 'zero-less- than' ) 

Returns a true (-1) flag if n is less than zero. 

( n - f ) 

( ' zero-equal ' ) 

Returns a true (-1) flag if n is equal to zero. 

{ nl n2 - f ) 

('less-than' ) 

Returns a true (-1) flag is nl is less than n2. 

( nl n2 - f ) 

( ' equal ' ) 

Returns a true (-1) flag if nl is equal to n2. 

( nl n2 - f ) 

( 'greater- than' ) 

Returns a true (-1) flag if nl is greater than n2. 

( nl n2 - f ) 

( 'not-equal' ) 

Returns a true (-1) flag if nl is not equal to n2. 

( nl n2 n3 - f ) 

Returns a true (-1) flag if the value nl is greater than or 
equal to the lower limit n2 and less than or equal to the upper 
limit n3 (i.e. n2 < nl < n3 } . 

{ nl n2 - n3 ) 

Compares nl and n2 and returns the greater value. 

( nl n2 - n3 ) 

Compares nl and n2 and returns the lesser value. 

( ul u2 - f ) 

( 'u-less-than' ) 

Returns a true (-1) flag if the unsigned value ul is less than 

the unsigned value u2. 
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STACK MANIPULATION OPERATORS 

.s ( - ) 

('dot-s') 

Prints a nondestructive display of the number of items on the 

parameter stack: 

3 5 ^ -s 3 5 ^ ok 

2drop ( nl n2 - ) 

Discards the top two items on the parameter stack. The FORTH 
code definition for 2drop is shown below: 

code 2drop ( nl n2 ) 

8 #n sp addq, ( increment the parameter stack ) 

{ pointer by 8, i.e. skip over the ) 

( top two items on the stack and ) 

( point at the previous item ) 

next; 

2dup ( nl n2 - nl n2 nl n2 ) 

Duplicates the top two items on the parameter stack. Leaves 
the duplicates on top of the parameter stack. The FORTH code 
definition of 2dup is shown below: 

n2 nl n2 ) 

{ put a copy of the second ) 
( 32-bit value on the stack ) 
( on top of the stack ) 
( do the same thing again. ) 

>r ( nl - I return stack: - nl ) 
('to-r') 

Removes nl from the parameter stack and places it on the 
return stack. 

?dup (n-nn) or (0-0) 
( 'question-dupe 1 ) 
Duplicates the value on top of the stack if it is nonzero. 

?stack ( - f ) 

( ' question-stack' ) 

Checks the status of the parameter stack. A false (0) flag 
will be returned if the stack is ok. A -1 will be returned if 
the stack is empty {if a stack underflow condition exists) 
and a 1 will be returned if the stack is full. 

?stackerr ( 'question-stack-error) 

{ " ) 

Uses ?stack to check for stack underflow or overflow. If one 
of these conditions has occurred ?stackerr will issue an 
appropriate error message and abort. 
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code 2dup 
sp 4 


( 
)d 


nl 
sp 


n2 - nl 
- ) move , 


sp 
next; 


4 


)d 


sp 


- ) move , 



depth ( - n ) 

Returns the number of items on the stack. 

drop ( nl - ) 

Discards the top item from the stack. The FORTH code definition 
for drop is shown below: 

code drop ( nl - ) 

4 #n sp addq, { increment the parameter stack pointer ) 

( by four, i.e. skip over the top item on ) 

{ the stack and point at the previous 

{ item ) 
next ; 

dup ( nl - nl nl ) 

Duplicates the value on top of the parameter stack. Leaves the 
copy on top of the stack. The FORTH code definition for dup 
is shown be low: 

code dup ( nl - nl nl ) 

sp ) sp -) move, ( move a copy of the 32-bit } 

( value on top of the ) 

( stack, onto the stack ) 

next; ( return ) 

i ( " n ) 

Puts a copy of the top item on the return stack on top of the 
parameter stack. During execution of a do... loop, the top item 
on the return stack is the index for the current loop. 

over ( nl n2 - nl n2 nl } 

Places a copy of the second item on the stack on top of the stack. 

r> { n - | return stack: - n ) 
('r-from') 

Transfers the top item on the parameter stack to the top of 
the return stack. 

r@ ( - n ) 

('r- fetch 1 ) 

Puts a copy of the top item on the return stack on top of the 
parameter stack. r@ performs the same function as i but r@ 
is normally used outside of ^o... loops. 

rot ( nl n2 n3 - n2 n3 nl ) 
('rote') 
Rotates the third item on the stack to the top of the stack. 

swab ( nl - n2 ) 

Exchanges the lower two bytes of the top value on the stack. 
Example: 

hex 

12345678 swab . 12347856 
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swap 



( nl n2 - n2 nl ) 

Exchanges the top two items on the parameter stack. 

code definition for swap is shown below: 



The FORTH 



code swap ( nl n2 

sp )+ dO move, 

sp )+ dl move, 

dO sp -) move, 

dl sp - ) move , 
next; 



n2 nl ) 

take n2 off the stack ) 

and place in the dO register ) 

take nl off the stack ) 

and place in the dl register ) 

put n2 on the stack ) 

put nl on top of the stack) 

return ) 
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INTEGER AND LOCAL VARIABI WORDS 



+ to 



( nl n2 - ) 

('plus-to' ) 

Format: nl <integer or local variable name> +to 

Adds nl to the current value of the integer or local variable 

specified by name. +to discards the value of the integer or 

local variable, n2, which was place on the stack when the 

name of the integer or local variable was executed and 

uses the address in the iv register (see the integer section 

in the Technical Reference Manual for more information) 

to find the location where the current value of the integer 

or local variable is stored. 



<locO> ( - n ) 

( 'brac-loc-zero' ) 

A special fast word used to access the first local variable 
on the return stack. Moves a copy of the return stack pointer 
into the iv register and then places a copy of the item on top 
of the return stack, the contents of the first local variable, 
on top of the parameter stack. 

<locl> ( - n ) 

( 'brac-loc-one' ) 

A special fast word used to access the second local variable 

on the return stack. Moves a copy of the return stack pointer 4+ 

into the iv register and then places a copy of the second item 

on the return stack, the contents of the second local variable, 

on top of the parameter stack. 

<local> ( - n ) 

Generic word used to access the third, and all subsequent local 
variables on the return stack. Uses the offset pointed to by 
the ip register to index into the return stack to find the 
contents of the desired local variable. Puts the address of 
the local variable in the iv register and puts the value of 
the local variable on top of the parameter stack. 



<locals> 



First local variable word compiled into a tForth word which 
uses local variables. Creates a storage area on the return 
stack which the local variables will use to temporarily 
hold their values . 



addr 



( n - a ) 

{'adder') 

Format: <name of integer> addr 

Returns the address of the storage location for the integer 

specified by name. 



into 



( - n ) 

Runtime code for integers located in integer tier 0. Puts the 

address of the integer's storage location in the iv register and 

places the current value of the integer on top of the parameter 

stack. 
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intl 
int2 

int3 
int4 
int5 
int6 
local 



off 



on 



to 



I - n ) 

Runtime code for integers located in integer tier 1. See into. 

( - n ) 

Runtime code for integers located in integer tier 2. See into. 

( - n ) 

Runtime code for integers located in integer tier 3. See intO. 

( - n ) 

Runtime code for integers located in integer tier 4. See into. 

( - n ) 

Runtime code for integers located in integer tier 5» See intO. 

( - n ) 

Runtime code for integers located in integer tier 6. See intO. 

( " ) 

Format: local <name for local variable) 

Creates a named local variable. The local variable is not 

initialized to any value. Executing the name of the local 

variable will place the value of the local variable on top 

of the parameter stack. 

{ n - ) 

Format: <name of local variable or integer) off 
Sets the value of the local variable or integer specified by 
name to zero. The value of the integer or local variable 
placed on the parameter stack when the local variable or 
integer name was executed is discarded. 

( n - ) 

Format: <name of local variable or integer) on 

Sets the value of the local variable or integer specified by 

name to negative one. The value of the integer or local variable 

placed on the parameter stack when the local variable or 

integer name was executed is discarded. 

{ nl n2 - ) 

Format: nl <name of local variable or integer) to 
Replaces the current value of the integer or local variable 
specified by name with the 32-bit value nl . The value placed 
on the stack when the local variable or integer name was 
executed is discarded. 
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MEMORY OPERATORS 

! { n a - ) 

{'store') 
Stores the 32-bit value n into memory starting at address a. 

+ ! ( n a - ) 
( 'plus-store* ) 

Adds the 32-bit value n to the 32-bit value located in memory 
starting at address a. The 32-bit value located in the memory 
location is replaced with the 32-bit addition result. 

-?&set ( a - f ) 

( ' minus- test-and-set' ) 

Sets the sign bit on the byte located in memory starting at 
address a. This makes the byte a negative value. If the byte 
was already a negative value before -?&set , a true (-1) flag 
is returned. If the byte was a positive value, a false (0) flag 
is returned. The 68000 'TAS' , 'test and set', instruction is 
used to implement this function. The 'TAS' instruction is special 
because it was designed such that the microprocessor cannot 
interrupt it between the testing and setting parts of its operation, 

0?&set ( a - f ) 

( ' zero-test-and-set ' ) 

Clears the sign bit on the byte located in memory starting at 
address a. This makes the byte a positive value. If the byte 
was already a positive value before 0?&set , a true (-1) flag 
is returned. If the byte was a negative value, a false (0) flag 
is returned. The 68000 'TAS' instruction is used to implement 
this function (see -?&set ). 

@ ( a - n ) 

('fetch') 

Places a copy of the 32-bit value located in memory starting 
at address a on top of the parameter stack. 

and! { b a - ) 
( 'and-store' ) 

Performs a bit-by-bit logical AND operation using b and the 
byte located in memory starting at address a. The byte length 
result is stored into memory at address a. 

c! ( b a - ) 
( 'c-store' ) 

The least significant 8 bits of the 32-bit value, b, on the 
parameter stack are stored into to memory starting at address a. 

c@ ( a - b } 
('c-fetch') 

Places the 8-bit value located in memory starting at address a 
in the least significant byte of a 32-bit value on top of the 
parameter stack. The upper three bytes (24 bits) are set to zero. 
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cmove 



dump 
fill 



( al o2 u - ) 

( * c-move' ) 

Moves the u bytes located starting at the source address al 

to the memory location starting at destination address a2. 

The general format is: 'source address 1 'destination address' 

'number of bytes to move' cmove. 

( addr len - ) 

( a u b - ) 

Replaces the u bytes located in memory starting at address a 
with the byte value b. The general format is: 'start address' 
'count' 'fill character' fill. 



move 



not! 



or] 



tip 



w: 



w@ 



xori 



( al a2 u - ) 
Special version of cmove. 

{ a - ) 

{ 'not-store' ) 

Takes the one's complement of the 8 bits of data located in 

memory starting at address a. The byte length result is stored 

into memory at address a. 

( b a - ) 

( 'or-store 1 ) 

Performs a bit-by-bit logical OR operation using b and the 

byte located in memory starting at address a. The byte length 

result is stored into memory at address a. 

( a - ) 

Performs a byte write operation to the specified address. 

Used for toggling soft switches. 

{ w a - ) 

('word-store') 

The least significant 16 bits of the 32-bit value, b, on the 

parameter stack are stored into to memory starting at address a, 

( a - w ) 

('word-fetch') 

Places the 16-bit value located in memory starting at address a 

in the least significant word of a 32-bit value on top of the 

parameter stack. The upper 2 bytes (16 bits) are set to zero. 

( b a - ) 

( 'exclusive-or-store' ) 

Performs a bit-by-bit logical XOR operation using b and the 

byte located in memory starting at address a. The byte length 

result is stored into memory at address a. 
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PROGRAM CONTROL STRUCTURES 



■loop 



<+loop> 



Compiling: ( - ) 

{ 'plus- loop' ) 

Executing: ( n - ) 

Format: do ... n +loop 

Program control structure used to implement definite loops 

During execution, +loop adds *n' to the current loop index, 

( n - ) 

( 'brac-plus-loop' ) 

Run-time code for +loop. Adds the decrement value 'n 1 to 
the current loop count and then decides whether the loop 
should be continued or terminated. 



<0bran> ( f - ) 

( 'brac-zero-bran' ) 

Run-time conditional branching primitive. A branch will occur 
if the flag passed to <0bran> is false (zero). Can only 
handle short {-8l<n<80 hex) branching distances. Used by 
while, until, and if. 

<0branl> ( f - ) 

( 'brac-zero-bran-long' ) 

Run-time conditional branching primitive. A branch will occur 
if the flag passed to <Obranl> is false (0) . Can be used for 
short and word (-8001<n<8000 hex) branching distances. Used by 
while, until, and if. 

<01eave> ( f - ) 

{ 'brac-zero-leave' ) 

Run- time code used to conditionally leave from a 'do... loop' 
or 'do...+loop' program control structure. The branch out of 
the program control structure will occur if the flag passed to 
<01eave> is false (0). Can only be used to branch forward 
short distances (n<80 hex). Currently, all leave and while 
branches use the long version of <01eave> . Also cleans up 
the return stack by reclaiming all of the return stack space 
used by the loop. Used to by used by while. 

<01eavel> ( f - ) 

( 'brac-zero-leave-long' ) 

Run-time code used to conditionally leave from a 'do... loop' 
or , do...+loop* program control structure. The branch out of 
the program control structure will occur if the flag passed to 
<01eavel> is false (0) . Can be used to branch forward word 
length distances (-8001<n<8000 hex). Also cleans up the 
return stack by reclaiming all of the return stack space used 
by the loop. Used by while. 
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<abort"> (fan-) 

( 'brac-abort-quote' ) 

Run-time code used by abort". Expects to be passed the 
address 'a' and length 'n' of an error message string and a 
flag 'f indicating whether or not the message should be 
displayed in the explain screen. 

<bran> { - ) 

( 'brac-bran' ) 

Run- time unconditional branching primitive. Always causes 
a branch to occur. Can only handle short (-8l<n<80 hex) 
branching distances. Used by again and else. 

<branl> ( - ) 

( 'brac-bran- long' ) 

Run-time unconditional branching primitive. Always causes 
a branch to occur. Can handle short <-8l<n<80 hex) and 
word (-8001<n<8000) length branching distances. Used by 
leave and else. 



<do> 



< leave > 



<loop> 



<quit> 



{ nl n2 - ) 

('brac-do') 

Run- time code for do. Expects to be passed a loop index, 

n2, and limit, nl, on the parameter stack. Takes both values 

off of the parameter stack and then pushes first the limit onto 

the return stack and then the count (limit-index). 

( " ) 

( 'brac-leave' ) 

Run-time code used to unconditionally leave from a 'do... loop* 

or 'do...+loop' program control structure. Can only be used to 

branch forward short distances (n<80 hex) . Currently, all 

leave and while branches use the long version of <leave>. 

Also cleans up the return stack by reclaiming all of the return 

stack space used by the loop. Used by leave. 

( - ) 

( 'brac-loop' ) 

Run- time code for loop. Subtracts one from the value on 

top of the return stack (the count value for a 'do... loop') and 

then checks to see if the count has reached zero. If the 

count has reached zero, <loop> removes the limit and count 

from the return stack and terminates the loop by allowing 

program execution to continue on the the code which follows 

the 'do... loop'. If the count has not reached zero, "jumps" 

back to the code which immediately follows the do. 

( - ) 

( 'brac-quit' ) 

Low-level word used by quit. 
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again 



abort" 



begin 



{ " ) 

Format: begin ... again 

Used to implement endless loops. All code between the begin 

and again will be executed endlessly (leave, while, and 

exit can be used to terminate ' begin ... again ' endless loops). 

( f - ) 

( 'abort-quote* ) 

Format: f abort" ccc" 

If the flag passed to abort" is true (nonzero) , a forced 

system abort process will occur. A beep will be issued, the 

message between the quotes will be displayed on the explain 

screen, the parameter stack will be cleared, and quit will be 

executed (to start FORTH running again), abort" must be 

used within a colon definition. 

( " ) 

Format : begin . . . again 

begin . . . until 

Used to mark the start of an endless or indefinite program loop. 



do 



Compiling: 
Executing: 
Format: nl 
nl n2 do 



( - ) 

( nl n2 - ) 
n2 do ... loop 
... n3 +loop 



Marks the start of a definite program loop. During execution, 
do takes the index ' n2' (start count) and limit 'nl' (end count) 
for the loop from the parameter stack and transfers the limit 
and the loop count (limit-index) to the return stack. 



else 



Compiling: ( - ) 

Executing: ( f - ) 

Format: if ... else ... then 

Inner decision point in the 'if .. .else. . .then' conditional program 

control structure. During execution, if the flag passed to 

else is true (nonzero) , the code between the else and the 

then will be executed. Otherwise, program execution will 

continue on to the code which immediately follows the then. 



execute ( n - ) 

Executes the word corresponding to the token 
the stack. Example: 



n' passed on 



.s execute empty 



exit 



( " ) 

Immediately and unconditionally terminates execution of the 
current definition and transfers control to the definition which 
contains the current definition. 
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if Compiling: ( - ) 

Executing: ( f - ) 

Format: if ... then 

if ... else . . . then 

Marks the start of the 'if... then' or 'if .. .else. . .then' 

conditional program control structures. During execution, if the 

flag passed to if is true (nonzero) , the code between the if 

and the then, or the code between the if and the else will 

be executed. Otherwise, program execution will be routed to 

the code which immediately follows the then (if the 'if... then 1 

structure is being used) or to the code between the else 

and the then (if the 'if .. .else. . .then' structure is being used). 

interpret ( a 1 - ) 

interpret is the main word involved in the running FORTH. 
interpret performs the following actions: 

1. Takes as inputs the address and length of a block of user 
input text. 

2. Advances through the text, word by word. The word word 

is used to isolate individual input "words" (a sequence of 
characters surrounded by spaces or tabs). Each time word 
is used it will return the address and length of the next 
word in the input text block to interpret. The in system 
variable is used to mark word's progress through the input 
text. 

3. Next, interpret passes the address and length returned by 
word to find, find will check to see if the string 
represented by the address and length contains the name 
of a word which can be found in the dictionary using the 
current vocabulary search order. If the system is in the 
compiling state, the word will be compiled into the definition 
currently being constructed. If the system is not in the 
compiling state, the word will be executed immediately 
(using execute) . 

4. If the string represented by the address and length does 
not contain the name of a FORTH word, interpret will pass 
the string address and length to number, number will 
try to convert the string to a number. If the number 
conversion process is successful and the system is in the 
compiling state, the converted number will be compiled as 

a literal into the definition currently being compiled. If 
the system is not in the compiling state, it will be placed 
immediately on the parameter stack. 

5. If the string cannot be found in the dictionary, and cannot 
be converted to a number, interpret will issue an error 
message to indicate that it does not recognize the input. 

6. If there is more user input text to process, interpret will 
repeat the steps above. If the user input text has been 
exhausted, interpret will terminate execution and let 

quit (the word which calls interpret) get more user input. 
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leave ( - ) 

Immediately and unconditionally reroutes program execution 
out of the current "looping" program control structure. 
May be used in 'begin' loops or in 'do' loops. 

loop { - ) 

Format : do ... loop 

Marks the end of the 'do... loop' definite loop program control 
structure. During execution, loop will decrement the loop 
count by one and compare the new count to zero. If the count 
has reached zero, loop will terminate the loop by routing 
program execution to the code which immediately follows it. 
Otherwise, loop will route program execution back to the 
code which immediately follows do. 

nest ( - ) 

Used by all words which start program control structures. 
If a program control structure is being used interactively, 
nest compiles an assembly language "jump to the nesting routine" 
instruction, records the address of the instruction, and 
increments the nesting level by one. This address will be used 
later when the temporarily compile code must be moved to the 
execution buffer for immediate execution. If a program control 
structure is not being used interactively, nest will simple 
increment the nesting level, stored in the system integer 
nesting, by one. See unnest. 

quit ( - ) 

quit is the word which runs FORTH. Clears the return stack 
and puts the system in the interpreting state. After quit is 
executed the system will be waiting for user input 
to interpret and execute. A high-level definition of quit is: 



quit ( - ) 
begin 



again 



clear the return stack ) 
get a block of user input text ) 
interpret the user input text ) 
' ok" cr 
do this endlessly ) 



then { - ) 

Format: if ... then 

if ... else . . . then 
Marks the end of the 'if... then' or 'if .. .else. .. then' conditional 
program control structures. 



- 177 - 



urines t 



until 



( " ) 

Used by all words which end program control structures. 
Decrements the nesting system integer by one and, if 
nesting has been reduced to zero and the system is not in 
the compilation state, moves the temporarily compiled 
program control structure code up to the execution buffer 
and causes it to be executed immediately. If the system 
is in the compilation state, unnest simple decrements 
nesting by one. 

( f - ) 

Format : begin ... f until 

Conditional exit/branching word used at the end of the 

'begin. . .until* indefinite loop program control structure. 

If the flag passed to until is true (nonzero) , until will 

terminate execution of the loop by allowing program execution 

to continue on to the code which immediately follows itself. 

If the flag is false (0), until will reroute program execution 

back to the code which immediately follows the begin. 



while 



{loop} 



{while} 



Compiling: ( - ) 










Executing: ( f - ) 










Format: begin . . . while 


( .. 


while ) 


. . . 


again 


begin . . . while 


{ .■ 


while ) 


. . . 


until 


do ... while { 


... 


while 


) 


loop 


dO ... while ( 


. . . 


while 


) 


+loop 



Inner decision/branching point in the 'begin. . .until' , 
'begin. . .again' , 'do... loop', or 'do...+loop' program control 
structures. During execution, if the flag passed to while is 
true (nonzero) , the code between the while and the next while 
until, again, loop, or +loop will be executed. If the 
flag is false, while will immediately reroute program execution 
out of the current loop (to the code which follows the next 
until, again, loop, or +loop) . 

( nl n2 - ) 

( 'curly-loop' ) 

Shared routine used by the loop termination words loop, +loop 

until and again. Used during compile time to compile the 

lower level branching primitives used by the loop termination words 

and to resolve and compile the delta branching distances used by 

the lower level branching primitives. 

( " ) 

( 'curly-while' ) 

Shared routine used by the words used to exit from loop program 

control structures: while and leave. Compiles the lower 

level branching primitive used by the exit word and reserves a 

two byte space for the delta branch distance used by the branching 

primitive 
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CHARACTER I/O WORDS 



Compile time: { - ) 
Run- time: ( - addr len ) 
( 'quote' ) 
Format: " ccc" 

When used during compilation, lays the string between quotes, 
and the runtime code <"> , into the definition being compiled. 
At run time the address and length will be left on the parameter 
stack. When used interactively leaves the string characters in 
the f tib' and returns the address and length on the stack. 
The first n must be surrounded on both sides by at least one 
space or tab. Caution: Always double-check for the presence 
of the closing " . If the closing w is missing, the compiler 
will continue appending program text into the string being 
constructed in the definition until either the dictionary fills up 
or until some other error message is generated. 



"to 



( addrl nl addr 2 n2 - ) 

{ 'quote- to' ) 

Format: " ccc" < string name> "to 

Stores the string specified by the address and length (addrl 

and nl) into the string integer specified by name. The address 

and length (addr2 and n2) of the current string stored in the 

string integer, which were placed on the stack when the name 

of the string integer was executed, are discarded, "to adjusts 

the string integer's storage area size to accomodate the length 

of the new string data. 



( - ) 

( ' paren ' ) 

Format: { ccc ) 

{ is the FORTH commenting word. All characters between the 

starting left paren and the closing right paren are considered 

to be comments and are ignored by the FORTH compiler. ( must 

be surrounded on both sides by at least me space or tab. 

Comments may not be nested, i.e., don't use parentheses within 

comment statements. 



■bit7 



( char - char' ) 

{'plus-bit-7') 

Sets the seventh bit in the character byte 



-trailing 



( addr len - addr len' ) 

( 'minus- trailing' ) 

Strips the trailing spaces from the string located at address 
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( - ) 

{'dot-quote') 
Format: . " ccc" 

May be used interactively or compiled into a definition. The 
compile-time action of . " is to lay the string between quotes 
into the definition being compiled. The run-time action of . " 
is to type the string between quotes out to the current output 
device. The . " must be surrounded by at least one space or 
tab . Example : 



<"> 



<"to> 



." Hello" Hello 



( used interactively ) 



: SayHi ( - ) , " Hello again." ; { compiled into a ) 
SayHi Hello again. ( definition. ) 

( - addr len ) 

( * brac-quote' ) 

<"> is the run- time code for the word " . Pushes the address 

and length of the string on the stack. 

( addrl nl addr2 n2 -> addr3 n3 ) 

( 'brac-quote-to' ) 

Run- time code for "to . 



<demit> ( char x y - ) 

( 'brac-display-emit' ) 

Draw the character at position x,y on the screen. 

<remit> { char - ) 

( 'brac-raw-emit * ) 

Raw emit to the screen. 

<word> ( addrl addr2 - addr 3 n addr4 ) 
( ' brac-word' ) 

Lower level routine used by word . Looks for the next word 
in the input stream which is surrounded by at least one space 
Takes the start address, addrl; and end address, addr2; of a 
region of text to search. Returns the address where the next 
search should commence, addr3; the length of the word found, 
n; and the address where the word found is located, addr4. 



ascn 



( - n ) 

Format: ascii <char> 

Returns the ASCII value of the single character which 

immediately follows it. 



becomes 



{ 



) 



check 



( addr n - ) 

Format: <string integer name> check 

Prints the ASCII values for each character in the string currently 

stored in the string integer specified by name. If the string 

integer is empty, an error message is displayed. 
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cr ( " ) 

Cc-r') 

Emit a carriage re turn/ line feed to the current active output 
devices . 

crlfscroll ( - ) 

Emit a carriage return and linefeed. Also blank the new 
line out and scroll if necessary. 



ctl 



demit 



eemit 



( ' control * ) 

Format: ctl <char> 

Turns the character which immediately follows it into a 

control character by setting the three most significant bits 

in the character byte to zero. 

( c - ) 

( 'display-emit' ) 

Emit the character to the screen. If the character is a 

cr perform a carriage return/ linefeed and scroll if necessary. 

If the character is the 'del' (delete) character erase the 

previous character on this line (if any) . 

( c - ) 

{ 'editor-emit' ) 

Emit the character to the editor. 



emit 



key 



( c - ) 

Output the character to all active output devices. The 
allowable output devices are the screen (see demit) , 
the parallel port (see pemit ), the editor (see eemit), 
and the serial port (see semit) . 

( - c ) 

Waits until a printable character (8<ascii code<80 hex) is typed 

at the keyboard. Returns the ASCII value of the character 

on the stack. 



pemit ( char - ) 

( 'parallel-emit' ) 

Send the character out through the parallel port. 

rub ( - ) 

Erase the previous character on the current line (if any) . 

scanfor ( c - ) 

Looks for the next word in the current input stream which 
is surrounded by the delimiter character, c. Sets the in, 
str, and len system variables. 

space ( - ) 

Emit a space to the current active output devices. 

spaces ( n - ) 

Emit 'n' spaces to the current active output devices. 
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word ( - ) 

]] Looks for the next word in the current input stream which 
] is surrounded by at least one space. Sets the in, str, and 

len system variables accordingly. 
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NUMERIC I/O WORDS 



( nl - n2 ) 

( f sharp ' ) 

Format: n <# ... # ... #> 

Extracts the lowest order digit from the number on top of the 

stack and inserts it into the formatted numeric string being 

constructed in the pad. 



#> 



#s 



{ nl - a n2 ) 

( 'sharp-greater' ) 

Format: n <# ... #> 

Removes the number from the top of the stack and returns 

the address and length of the formatted numeric string which 

has been constructed in the pad (prepares the formatted 

numeric string for type). 

{ n - ) 

( 'sharp-s' ) 

Format: n <# ... #s ... #> 

Calls # until the number on top of the stack has been reduced 

to zero. 



( n - ) 

('dot') 

Prints the signed value on top of the stack followed by a 

trailing space. The definition of . provides a good example 

of the use of the pictured numeric output operators: 



( 



Output n as a signed or unsigned number 



with 1 trailing space. 
dup 



abs 



#> 

type 

space 



#s 



swap 
sign 



) 



duplicate the number ) 

get absolute value of number ) 

start number formatting. . . ) 

convert all digits in number to ) 

ascii characters and insert in ) 

the string ) 

check the sign of the original number ) 

if it was negative, insert a '-' here ) 

clean up stack, set stack for type ) 

display the string ) 

follow numeric string by one space ) 



.r 



{ n w - ) 

('dot-r') 

Prints the signed value 



in a field which is 



spaces wide 



<# 



( n - n ) 

( ' less-sharp' ) 

Format: n <# ... #> 

Marks the start of a pictured numeric conversion process. 

The words #, #> , #s, <#, hold, and sign are all 

used to construct the formatted string in the pad. 
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decimal 



digit 



Selects base ten (decimal' 
input/output conversions . 



as the base used for all numeric 



{ nl n2 - n3 c ) 

Extracts the least significant digit from the number, nl, on the 
stack {using the specified base, n2) and leaves ascii value for 
the digit, c, and the remaining number, n3 on the stack, digit 
performs the following actions: 1. takes the number nl from the 
stack and divides it by the base, n2 2. leaves the quotient of the 
division, n3, and the ASCII value of the remainder, c, on top of 
the stack. 



hex 



hold 



number 



sign 



u. 



u.r 



( " ) 

Selects base sixteen (hexadecimal' 

numeric input/output conversions. 



as the base used for all 



( c - ) 

Format: <# ... ascii c hold ... #> 

Inserts the character (represented by the ASCII value) on top 

of the stack into the formatted numeric string currently being 

constructed in the pad. 

( a nl n2 - f | If conversion is not successful. ) 
( a nl n2 - n3 f | If conversion is successful. ) 
Converts the string of length nl located starting at address a 
to a number, n3, using base n2. If the string-to-number 
conversion is successful, the converted number and a true 
(-1) flag will be left on the stack. If the string-to-number 
conversion is not successful (non-numeric characters in the 
string) a false (0) flag will be left on the stack. 

( n - ) 

If the number on top of the stack is negative, sign will 
insert a minus sign into the formatted numeric string being 
constructed in the pad. 

{ n - ) 

Prints the unsigned value on top of the stack followed by 

a trailing space. 



( n w - ) 

Prints the unsigned value 



n' in a field which is 



spaces wide 
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DEFINING WORDS 

<string> ( - addr len ) 
( 'brac-string' ) 

Run- time code for string integers created with the defining 
word string. Pushes the address and length of the string 
stored in the string integer on the stack. 

: ( " ) 

( 'colon' ) 

Format: : <name> ...words... ; 

Defining word used to create new definitions. Puts the system 

in the compiling state, creates a new dictionary header using 

<name> , sets the smudge bit in the dictionary header so the 

definition will not be visible until completed. All words between 

the <name> and the ; will be compiled into the definition. 

The run- time action of words created by : is to execute the 

words which comprise the definition. 

array Compiling: ( n - ) 
Executing: ( - a ) 
Format: n array <arrayname> 

During compile- time, array allocates 'n* bytes in the dictionary 
for an array of data and creates a header to mark the start of 
the data area. The run- time action of the child words created 
by array is to push the address of the start of the array data 
area on the stack. 

64 array message 
message . 293036 

integer Compiling: ( n - ) 
Executing: ( - n ) 
Format: n integer <integername> 

At compile-time integer creates a named 4-byte data location 
and initializes the location with the value 'n' . The run- time 
action of the child words created by integer is to push the current 
contents of their 4-byte storage location on the stack. 

string 



Compiling: 


{ 


a n 


- ) 




Executing: 


( 


- a 


n ) 




Format : 


11 


ccc" 


string 


<stringname> 



At compile-time string creates a named, multi-byte string storage 
area in the dictionary and initializes the storage area with the 
characters between the quotes. The runtime action of the child 
words created by string is to push the address and length of the 
the string currently stored in the string storage area on the stack 

vocabulary { - ) 

Format: vocabulary <vocabname> 

Create a new but inactive vocabulary. The name for the new 
vocabulary will reside in the vocabulary which was open when 
the new vocabulary was created. When the child word created 
by vocabulary (<vocabname>) is executed, it will place itself 
first in the vocabulary search order. 

- 185 - 



DICTIONARY MANAGEMENT WORDS 

<addto> ( n - ) 

('brae -add to' ) 

Close the current open vocabulary and open the vocabulary 

specified by the token 'n'. 

<becode> ( n - ) 

( 'brac-becode' ) 

Remove the code corresponding to the token ' n ' . 

<behead> { a - ) 

{ 'brae -behead' ) 

Remove the header located at address 'a*. 

<bevoc> ( n - ) 

( 'brac-bevoc' ) 

Completely eliminate the vocabulary specified by the token ' n'. 

<csize> ( a - n ) 

( 'brac-code-size' ) 

Returns the code size 'n' , in bytes, of the word whose code 

is located at address 'a'. 

<deactivate> ( n - ) 

( 'brac-deactivate' ) 

Removes the vocabulary specified by the token 'n' from the 
current search order (removes its token from the 'active' 
array, see active) . 



<empty> 



( n - ) 

{ 'brac-empty 1 ) 

Purges all words from the vocabulary specified by the token 'n' 



<eta> 



) 



( a n - I If token 'n' is not found. 

( al n - a2 | If token 'n' is found. ) 

Takes the vocabulary address 'al' and the encoded token 

value 'n' and, if successful, returns the encoded token address 



<purge> 



add to 



behead 



{ n - ) 

( 'brac-purge' ) 

Removes the word corresponding to the token 'n' from the 

dictionary. 

( " ) 

Format: addto < vo cab -name > 

Opens the vocabulary whose name immediately follows addto. 

( - ) 

Format: behead <name> 

Remove the header of the definition whose name immediately 

follows behead. 
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bevoc 



createvoc 



( - ) 

Format: bevoc <name of vocabulary> 

Removes the vocabulary specified by name, and all words in 

the vocabulary, from the dictionary. 

( al n - a2 ) 

Create an empty vocabulary using the image of an empty 
vocabulary located starting at address 'al' and assign it 
the token 'n'. Return address 'a2* is unused. 



csize 



deactivate 



( - n ) 

( 'code-size' ) 

Format: csize <name> 

Returns the code size of the word specified by <name> . 

( " ) 

Format: deactivate <vocab-name) 

Removes the vocabulary whose name immediately follows 

deactivate from the current search order. 



empty 



emptyvoc 



eta 



existing 



( " ) 

Purges all words from the current vocabulary. 

in the forth vocabulary cannot be purged. 



The words 



( - addr ) 

Returns the address of the 18 decimal byte image of an 

empty vocabulary. 

( token - addr f ) 

Tries to return the address of the token table entry for the 

token. If successful returns the token table entry address 

and a true (nonzero) flag. Otherwise, returns a false (0) 

flag. 

( " ) 

Displays the names of and parents of all existing 

vocabularies . 



forth 



mvoc 



( " ) 

This is the main 'tFORTH' vocabulary. It contains all of the 

'standard' FORTH words supported by 'tFORTH' and all of 

the 'tFORTH' FORTH extension words. Execution of forth 

will cause the forth vocabulary to become the first 

vocabulary in the search order (its token will be placed first 

in the 'active' array). 

( a - n ) 

Returns the token 'n* of the vocabulary which contains 

address ' a' . 



name 



{ n - ) 

Print the name of the definition which corresponds to the 

token ' n' . 
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purge { - ) 

Format: purge <name> 

Removes the word specif ed by <name> from the dictionary. 

recycle ( n - ) 

Reclaims the token table space for the token ' n ' . 

retop { a - ) 

Lower level word used to open a vocabulary. Moves 

the upper half of the dictionary up so that the new top 

of dictionary is at address 'a'. 

safety ( a - ) 

Reclaim the token table space for the token whose header 
is located at address 'a'. 



searched 



setcodesize 



vocab 



vocab? 



vopen 



words 



( " ) 

Display the vocabulary search order. 

( - ) 

Set the code size field for the current open vocabulary. 

Set the odd size flag if necessary. 

( ~ ) 

Move the current execution vocabulary to the top of the 
search order by placing its token at the start of the 
active array. 

( token - f ) 

Returns a true (nonzero) flag if the token on top of the 
stack it the token for a vocabulary. Returns a false (0) 
flag otherwise. 

( token - addr ) 

Returns the address of the opening point for the 

vocabulary which corresponds to the token. 

( ~ ) 

Displays a list of all words in the vocabulary which is 

first in the search order. 
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COMPILATION WORDS 

Icsp ( - ) 

( ' store-csp' ) 

Used to save the return stack pointer value away before a 

compilation process occurs. 

* ( - token ) 
('tick') 

Format: ' <name> 

Returns the token for <name>: 

* words . 1A5 ok 

( n - ) 

( 'comma' ) 

Lays the 32-bit value 'n' into the next free location in the 

code area. The here pointer always points at the next free 

location in the code area. The here pointer is incremented by 

4 bytes. 

♦ table { n - a ) 

{ 'plus-table' ) 

Takes a token table entry number and calculates and returns 

the address of the corresponding token table entry field. 

; ( - ) 

( 'semi-colon' ) 

Used to terminate colon definitions. If the colon definition does 

not use local variables, ; causes the word <;> to be compiled 

into a definition. If the colon definition does use local 

variables, ; causes the word <;lp> to be compiled into a 

definition. 

<;> Parameter: ( - ) Return: ( nl n2 - ) 
( 'brac-semi' ) 

Run- time word compiled by ; . Pops two word length return 
values off of the return stack. The first value popped, 'n2' , 
is used to reconstruct the ip register. The second value 
popped is used to reconstruct the ct register. 

<;lp> ( - ) 

( 'brac-semi-local' ) 

Run- time exit word compiled at the end of colon definitions 
in which local variables are used. Compiled by ; . Pops two 
word length return values off of the return stack (see <;> ) 
and then reclaims all return stack local variable storage. 
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<find> ( al a2 nl - a2 f | If not found ) 
( al a2 nl - a3 . n2 t | If found ) 

Searches for the name specified by the string at address ' a2' 
of length 'nl 1 in the vocabulary which starts at address ' al'. 
If the word is found in the vocabulary, <find> will return the 
dictionary header address ' a3' for the word, the token for the 
word f n2' and a true flag (nonzero). If the word is not found 
in the vocabulary <find> will return the original name string 
address 'a2 f and a false (zero) flag. 



?csp 



{ - ) 

( 'question-csp' ) 

Compares the current return stack pointer to the return stack 

value saved away previously in the csp system integer. If the 

two addresses are not equal the system will abort with an 

" unpaired" message. The return stack pointer address is saved 

away at the start of the compilation of a colon definition (in :) 

and is checked at the end of compilation (by ; ) . 



?pairs ( - ) 

( ' question-pairs ' ) 

Checks for properly paired conditional statements. Aborts 

and issues an error message if it senses an improperly paired 

conditional. 



align 



( " ) 

Aligns the here pointer to an even address boundary. 



allot 



( n - ) 

Tries to allocate 'n' bytes in the code area of the currently 
open vocabulary. If no vocabularies are currently open, or if 
'n' bytes are not available in the open vocabulary, the system 
will abort, allot allocates space by adding 'n* to the address 
stored in the here system integer. 



assign ( al a2 n - ) 

Assigns a token to and builds a header for a new definition in 
the vocabulary specified by the address 'al' using the name 
located at the address 'a2' with the length 'n'. 

backelse ( nl - n2 nl ) 

Used by then to backpatch a forward else branch offset. 
If the delta branch distance is short (-8l<delta<80) , the code 
between the else and the then will be shifted one byte 
towards lower memory and the shift distance, -1, will be 
returned as the second item on the stack, n2. If the delta 
branch distance is word length (-8001<delta<8000) no code 
movement will occur and a shift distance of will be returned 
as the 'n2' parameter. 
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blit 



( - n ) 

('byte-literal' ) 

Code definition which transfers the byte-length literal value 

pointed to by the instruction pointer to the parameter stack 

and increments the instruction pointer by one byte. Used by 

literal. 



c, 



compile , 



create 



decode 



( - a ) 

('c-tick') 

Format: c' <name> 

Returns the address of the code field (code area) of the 

definition specified by <name>. 

( c - ) 

( 'c-comma' ) 

Compiles the byte length value ' c' into the next available 

location in the code area (at the address pointed to by the 

here pointer. ) 

{ n - ) 

( 'compile -comma' ) 

Lays the token value passed on the stack into the dictionary 

at the current here address. Checks the size of the value. 

If the token value is greater than $100 (bigger than one byte) , 

compile will w, the token value into the dictionary. If the 

token value is less than $100, compile will use c, to place 

the token into the dictionary. 

( - ) 

Format: create <name> 

Assigns a token to and creates a header entry for <name> in 

the current open vocabulary. 

( n - token ) 

Takes the encoded token number from the top of the stack, 
decodes it, and returns the decoded token number on top of 
the stack. 



diff? 



doloc 



( al a2 n -> 1 If strings match ) 
( al a2 n -> a3 -1 1 If strings don't match ) 
Compares the first *n' characters in the strings located at 
addresses ' al ' and 'a2'. If the first 'n' characters in the 
two strings match, a false (0) flag is returned. If the first 
' n* characters in the two strings do not match, a true (-1) 
flag and a pointer to the first dissimilar character in the 
first string (the string pointed to by 'al'), 'a3', is returned. 

( - f ) 

Used by interpret. Only used within a colon definition. 
Checks to see if the word just extracted from the input stream 
belongs to a local variable. If the word is the name of a local 
variable, compiles the code which will place the value of the 
local variable on the stack during execution into the definition 
and returns a false (0) flag. If the word is not the name of a 
local variable, returns a true (nonzero) flag. 
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encode ( nl - n2 ) 

Takes the decoded token number from the top of the stack, 
encodes it, and returns the encoded token number on top of 
the stack. 



find 



( a nl - n2 true 1 If found in search order ) 
( a nl -> false 1 If not found in search order ) 
Searches the through the dictionary (uses the current search 
order) looking for the definition whose name matches the name 
at the address 'a' with length 'nl*. If a match is found, find 
will return a true (nonzero) flag and the token which 
corresponds to the definition. If a match is not found, find 
will return a false (0) flag, find uses the lower level word 
<find> . 



fnderr 



( 



) 



( * find-error' ) 

Prints a "can't find" error and aborts 



forward ( - ) 

free token ( - ) 

Prints an "unassigned token" message and aborts. 

immediate ( - ) 

Sets the immediate bit (bit 6) of the most recently defined 
colon definition so that whenever the word is encountered 
during compilation, it will be compiled rather than executed. 
The address of the header entry for the most recently defined 
colon definition is kept in the newest system integer. 

lit ( - n ) 

Code definition which transfers the long-word (32-bit) literal 
value pointed to by the instruction pointer to the parameter 
stack. The instruction pointer, ip, is incremented by by 4 bytes 
Used by literal. 

literal ( n - ) 

literal is used to compile constant data into a definition. 
literal will also compile the token of a word which will push 
the constant data onto the parameter stack when the definition 
is later executed. If the value can be represented with one byte 
of data, literal will compile the toke for blit into the new 
definition. If the value can be represented with two bytes 
of data, literal will compile the token for wlit into 
the new definition. If the value can only be represented with 
4 bytes of data, literal will compile the token of lit into the 
new definition. 

n f ( - a ) 

Cn-tick') 
Format: n' <name> 

Returns the address of the dictionary header area for the 
word specified by <name> . 
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raddr ( - a ) 

Copies the return information stored on the return stack. 
Uses the return information to calculate the address where 
the next token to be executed in the definition at the next 
higher execution level is located (calculates the previous 
location of the ip pointer). Used by compile. 

recycled token 

( - token ) 

recycledtoken checks to see if any previously assigned tokens 
are now available for re-assignment. If a previously assigned 
token is available, recycledtoken will return the token value 
on the stack. If no previously assigned tokens are available 
a token value of will be returned. 

same? { al a2 n -> f ) 

Returns a true (nonzero) flag if the first ' n* characters 
in the strings located at 'al' and ' a2' are the same. 

stub ( - ) 

Format: stub <name> 

Uses create to assign a token to and create a dictionary 
header for <name>. Stores a in <name>'s token table entry so 
<name> will not have any corresponding code area. 

w, ( w - ) 

( 'w-comma 1 ) 

Stores the word length value ' w* into the next available spot 

in the code area of the currently open vocabulary. 

wlit ( - n ) 
('w-lif) 

Code definition which transfers the word-length (16-bit) literal 
value pointed to by the instruction pointer to the parameter 
stack and increments the instruction pointer by two bytes. Used 
by literal. 

[ ( - ) 

{'left-bracket* ) 

Turns the FORTH compiler on. 

[*3 ( - token ) 

( 'brac-tick-brac' ) 

Format: : <name> ... ['] <definition-name> ; 

['] must be used within a colon definition. ['] will return the 

token for the definition whose name immediately follows it 

in the colon definition. 

: test ( - ) [ ' ] words . ; 
test 1A5 ok 

[compile] ( - ) 

( ' brac-compile-brac* ) 

Compiles the token of the word which immediately follows 

it into the definition currently being constructed. 

- 193 " 



( - ) 

{ ' right-bracket* ) 

Turns the FORTH compiler off. 
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DISK I/O WORDS (HIGH-LEVEL) 
!ptr 



( n delta - > 

Store the value n into the save block area. 



<load> 



<rblock> 



<wblock> 



?diskerror 



@ptr 



block 



copy 



copyO>0 



( n - ) 
Reads block 
contents . 



from disk into memory and interprets its 



) 



( addr b# - flag 
Read block number ' b* into the buffer located at address 
'addr'. If no error occurs during read, the flag returned will 
be false (0) . 

( addr b# - f ) 

Write the block of data contained in the buffer located at 
address 'addr' to block number ' b' on the disk. If no error 
occurs during the write operation the flag returned will be 
false (0). 

( n - ) 

?diskerror will take the error code from the parameter stack, 
analyze it, and print an error message which tells the user 
what type of disk error occurred. 

( delta - ptr ) 

Get a pointer from the system id area. 

{ n - ) 

Tries to read the contents of block number ' n f on the 

disk into the block buffer in memory. If block ' n' has 

already been read into the block buffer, block will 

do nothing. If block ' n 1 is not currently in the block 

buffer, block will read the contents of block *n f into 

the buffer and overwrite the current block buffer contents . 

( nl n2 n3 - ) 

Copy blocks number 'nl' through f n2' to the blocks starting at 

block number ' n3' . 

( nl n2 n3 - ) 

Copy blocks number 'nl' through 'n2' from the source disk to 

the blocks starting at block number 'n3 f on the destination 

disk. 



doff 


( - ) 


don 


( " ) 




Tries t 


driveO 


( - ) 


drivel 


( " ) 


ebuf 


( " ) 



Tries to turn the disk drives on, 
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format 
idblock 

load 
rblock 

rblocks 

recal 
rsector 
rtrk 
save? 

sideO 
sidel 
thru 

vsector 
wblock 

wblocks 

wsector 
wtrk 



( - ) 

Formats a disk using the IAI disk format. 

( - f ) 

Read one of the two edde (i/o flag) id blocks. The flag returned 
will be true (nonzero) if an error occurs during the read. 

( b - ) 

( addr b - ) 

Reads block # *b' from disk to the RAM buffer located 

starting at address 'addr'. 

( n b - n m ) 

Read 'n' blocks, starting at block number 'b', from disk into 

memory starting at the current location of the here pointer. 

( " ) 

( a sector# - errorcode ) 

( a track - errorcode ) 

( - ) 

Aborts if the disk is write-protected 



( 



( bl b2 - ) 

Loads block number 'bl' through block number 'b2' from disk. 

{ a sector# - errorcode ) 

( addr b - ) 

Write the block of data located in RAM starting at address 

'addr' to block number 'b' on the disk. 

( n b - n b ) 

Write 'n' blocks, starting with block 'b*, to disk from memory 

starting at the address of the here pointer. 

( addr sector# - errorcode ) 

( addr track - errorcode ) 
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DISK I/O WORDS (LOW-LEVEL) 

. <restore> ( - ) 

Restore subroutine. 

.<save> ( - ) 

Save subroutine address, 



<rdata> 



<rheader> 



( d2 = -1 if invalid crc or data field not found ) 

{ d3 = low word is crc read, high word is crc calculated ) 

( a6 = address of rbyte ) 

{ a5 = address of disk status register } 

( a4 = disk data register address ) 

( a3 = CRC table address ) 

( a2 = return address ) 

{ al = buffer address ) 

( d2 = returns with the address of info or -1 if not found. 

( a6 = address of rbyte ) 

( a5 = address of disk status register ) 

( a4 = disk data register address ) 

( a3 = CRC table address ) 

( a2 = return address ) 



<rsector> 



( 



a n - 



) 



<step> { - ) 

Step the drive head with interrupts off, 
the status register. 



Saves and restores 



<trackdump> 


( 


- 


<vdata> 


( 


d2 




( 
( 


d3 
a6 




( 
( 


a5 
a4 




( 
( 


a3 
a2 




( 


al 


<vsector> 


( 


a 


<wdata> 


( 


al 



) 



-1 if invalid crc or data field not found ) 

low word is crc read, high word is crc calculated ) 

address of rbyte ) 

address of disk status register ) 

disk data register address ) 

crc table address ) 

return address ) 

buffer address ) 



n - n ) 

( al = pointer to data ) 

( a2 = return address ) 

( a3 - pointer to crc table ) 

( a4 = pointer to disk data register ) 

( a6 = pointer to wbyte routine ) 

Writes a data field onto the disk using the table pointed to by 

the contents of the A 5 register. 



<wsector> 



( 



n 



n 



) 
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<wtrack> ( al = pointer to data ) 

( a2 = return address ) 

( a3 = pointer to crctable ) 

( a4 = pointer to disk data register ) 

( a5 = pointer to format information ) 

( a6 = pointer to wbyte ) 

( d2 = starting address information ) 



?diskrdy 

?trkO 

?wprot 

crc 

crctable 
iai-trk 
rbyte 



rheader 
r track 
step in 

stepout 

trackdump 
wbyte 



wsync 



wtrack 



"rimage 
wimage 



Writes one track of data to the disk, 

( - f ) 

Returns a true (-1) flag" if the disk is ready, 

( - f ) 

Returns a true (-1) flag if on track 0. 

( - f ) 

Returns a true (-1) flag if write protected. 

( nl n2 ■ n3 ) 



a3 = pointer to crctable ) 
a4 = pointer to disk data register ) 
d3 = contains the current crc value ) 
Writes a byte of data to the disk. 



- n 



a n n - n 



- ) 
Set dir signal to step in, 



) 



a3= pointer to crctable ) 
a4 = pointer to disk data register ) 
dO = the byte to be written with upper bits =0 ) 
d3 = contains the current crc value ) 
Writes a byte of data to the disk. 

dO = number of times to be written ) 
a4 = pointer to disk data register } 
Write n bytes of zeros to the disk. 

an-) 
Write track using IAI format to disk. 

- ) 
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CRT DISPLAY WORDS 

els ( " ) 

Clear the display screen. 

home ( - ) 

Positions the cursor in the first column of the first row on the 
screen (in the upper left hand corner). 

page ( - ) 

If the screen is the current output device, clears the screen and 
places the cursor in the upper left corner of the screen. 

setcur ( x y - ) 

Position the curson at x,y. 

window ( n - ) 

Set FORTH' s bottom display line to 'n' where K=n<=lD. 

voff { - ) 

Turn the video display off. 

von { - ) 

Turn the video display on and off, decide in high level. 
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SOUND GENERATOR WORDS 

beep ( - ) 

Make a beep. 

ringoff { - ) 

Turns off timer interrupts. 

thp ( n - ) 

Set up sound generator frequency. 

toff ( - ) 

Turn sound generator off. 

ton ( - ) 

Turn sound generator on. 

tone ( pitch duration - ) 

Emit sound with the specified pitch for the specified duration. 
The duration is specified in ticks. 
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KEYBOARD WORDS 



Ichar 



( char - ) 

Takes a character, as returned by <?k> , stores the character 
code in the system integer char , and stores a true (nonzero) 
value in the system integer char? (to indicate that a character 
is available. If the character is one of the "special" 
keys on the keyboard (KB1/2 , left shift , right shift , caps 
lock , left use-front , right use-front , left leap or right leap) 
Ichar will perform some special tests before storing the 
character code in char , If the special key is going down while 
one of the use-front keys is already down, and the special key is 
not the caps lock key, the special key will be marked as "down" in 
the modifiers array. If the special key is a caps lock key, the 
state of the modifiers array will not be affected. If the special 
key is going down while neither use-front key is down, the special 
key is marked as "down" in the modifiers array and, if the special 
key is one of the shift keys, the caps lock key is marked as "up" 
(off). If the special key is going up and it is a caps lock key, 
the state of the modifiers array is not changed. If the special 
key is going up and it is not a caps lock key, it is marked as 
"up" in the modifiers array. The final special key test checks to 
see if the caps lock key is currently down. If it is, the LED on 
the caps lock key will be lit. Otherwise, the LED will be unlit. 



<?k> 



( - f ) 

Uses <<?k>> to see if a key is available and returns a true 

(nonzero) flag if a character is available. 



<<?k>> ( - flag ) 

Returns a true (nonzero) flag if a key is available. First, 
checks to see if a key is currently available. If a key 
is already available, will exit immediately and return a true 
(nonzero) flag. If a key is not currently available, will spin 
in a loop calling do-event until either a key is available or 
until there are no more key events in the event loop. 



<key> 



( - char ) 

Get a key, set char? to zero to indicate that no keys are 
currently available, and, if the system is in the middle of 
recording a learn sequence, record the character. 



?auto 



( - f ) 

Returns a true (nonzero) flag if it is time to autorepeat 

the current character. 



?ctl 



( - f ) 

Returns a true (nonzero) flag if one of the USE FRONT keys is 

currently down. 



?ev 



( - f ) 

Returns a true (nonzero) flag if the keyboard event queue is not 

empty, if keyboard events are available. 
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?k { - f ) 

Return a true (nonzero) flag if the current character is not a 
special key. 

?kstat ( - n ) 

Returns the keyboard status. 

?kval ( - c ) 

Returns the character code stored in char . Used to "peek" at 
the current character without affecting its current character 
status. 

?lex ( - f ) 

Returns a true (nonzero) flag if the left leap key is 
currently down. 

?panic ( - f ) 

Returns a true (nonzero) flag if the user hits the panic stop 
key. 

?rex ( - f ) 

Returns a true (nonzero) flag if the the right leap key is 
currently down. 

?shift ( - f ) 

Returns a true (nonzero ) flag if either of the SHIFT keys is 
down. 



?t 



@k 



( - f ) 

Returns a true (nonzero) flag if a character is currently 

available. The character is consumed by ?t . 

( - c ) 

Returns the next 'physical* character (the character code as 

returned by do-event) . 



clear-auto ( - ) 

Turn off autorepeating. 

clear-special 

( " ) 

Clears out the shift state array to indicate that all of the 

special keys are up. 

clr-kbd ( - ) 

End playback of a learn sequence. 
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do-event ( - ) 

Removes a key event from the keyboard event queue and converts 
the event code into offset. The offset is used to index into a 
table which converts key press information into character 
information. Stores the character information into the system 
integer kval and stores a true (nonzero) flag into the system 
integer kstat to indicate that a key is available. If the 
character is one of the special keys, performs tests and actions 
similar to those performed by tchar (except do-event* s actions 
affect the shif tstate array instead of the modifiers array) . 



down? 



( n - f ) 

Checks to see if the special key corresponding to the number 
'n 1 is currently down. Returns a true (nonzero) flag if the 
key is down. 



keyboardoff ( - ) 

Turn keyboard scan off. 

keyboardon ( - ) 

Turn keyboard scan on. 

playback? ( - f ) 

Returns a true (nonzero) flag if there is a character to play 
back. 

playback ( - c ) 

Return the next character to be played back. 

record ( c - c ) 

Insert the character in the learn string currently being 
recorded. 

set-auto ( - ) 

Turn on autorepeating for the last key returned. 

sync-shiftkeys 

( " ) 

Store the actual physical states of the special keys, as 
stored in the system integer shiftstate , into the modifiers 
system integer. 

thislearn ( - addr n ) 

Return the address and length of the current learn string. 
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MODEM AND SERIAL I/O WORDS (HIGH-LEVEL) 

squish ( bytel byte2 byte3 byte4 - longword ) 

Uses the lowest order byte from each of the four values 
on the stack to create one longword (32-bit) which is 
returned on the stack. The byte taken from the value 
on top of the stack will end up in the most-significant 
byte position of the longword and the byte taken from 
the fourth value on the stack will end up in the least- 
significant byte position. 

talk ( - ) 

Connect phone to line. 

thres.43 ( - ) 

Set energy detect threshold to -43 dBm. 

thres.48 ( - ) 

Set energy detect threshold to -48 dBm. 

tt. disable ( - ) 

Disable touchtone encoder. 

tt. enable ( - ) 

Enable touchtone encoder. 

txcr. disable 

{ ~ ) 

Disable modem carrier. 

txcr. enable ( - ) 

Enable modem carrier. 



valid . tone . table 

( ~ 



) 



wordlen ( n - ) 

Sets the number of bits per word. 

<dial> ( addr len - ) 

Dial the string pointed to by 'addr' and 'len'. 

char>tone ( char - ) 

Send DTMF if valid tone found. 

char>pulses { char - ) 
Send pulses. 



dialchar 

getover 
getport# 



( char - ) 

Dials an ASCII char. 



( 



) 
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initmodem ( - ) 

Reset the modem. 

initphone ( - ) 

Initialize the modem and phone ACIA. 

initrs232 { - ) 

Initialize the serial port. 

port>mem ( addr len - ) 

Get a string of stuff into memory. 

pulses ( n - ) 

Send ' n * pulses . 

send . tone ( n - ) 

'n' is the row/col data. Send a 50 ms DTMF, 
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MODEM AND SERIAL I/O WORDS (LOW- LEVEL) 
<box> ( xl yl x2 y2 flag - ) 
<line> ( xl yl x2 y2 flag - ) 
<point> { x y flag - ) 

analog . loop . off 

( - ) 

Disable analog loopback. 

analog . loop . on 

{ - ) 

Enable analog loopback. 

digital. loop. off 

( " ) 

Disable digital loopback. 

digi tal . loop . on 

( ~ ) 

Enable digital loopback. 

filter. high ( - ) 

Set filter for normal operation. 

filter. low { - ) 

Set filter for call progress detection. 

init.ph.acia 

( " ) 

Set hpne UART to 1200 baud, 8 data bits, 1 stop bit, 

and no parity. 

modem. ans ( - ) 

Set to answer mode. 

modem. fsk ( - ) 

Set to 300 bits per second (bps) FSK. 

modem. orig ( - ) 

Set to originate mode. 

modem. psk ( - ) 

Set to 300 bits per second (bps) PSK. 

mute ( - ) 

Mute phone. 

offhook ( - ) 

Place the phone off hook. 

onhook ( - ) 

Place the phone on hook. 
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ph.rx ( byte ) 

Receive a byte from the telephone's rs232 port. 

ph.tx ( byte - ) 

Send a byte to the telephone's rs232 port. 

pll.fast ( - ) 

Set PLL to fast response. 

pll.slow { - ) 

Set PLL to slow response. 

row/ col . table 

{ - ) 

scrambler . disable 

( - ) 

Disable modem scrambler. 

scrambler . enable 

( " ) 

Enable modem scrambler. 

ser.rx ( - byte ) 

Receive a byte from the rs232 port. 



ser. 


, tx 


( byte - ) 
Send a byte to t 


spl. 


.off 


( ~ ) 

Set pin 13 low. 


spl. 


,on 


( " ) 

Set pin 13 high. 


sp2. 


,off 


{ " ) 

Set pin 16 low. 


sp2. 


,on 


( - ) 

Set pin 16 high. 
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tFORTH SYSTEM INTEGERS 

active Holds the address of the 'active* vocabulary array. 



applic 

auto 
base 

blk 
bound 

cbuff 

char 

char? 

clockO 

clockl 

crt 

csp 



Holds the address of the next available location in the 
header area of the current open vocabulary. 



Holds the number used to indicate the numeric base currently 
being used for all number I/O. 



During the interactive execution of program control structures, 
bound is used to hold the start address of the program control 
structures code which is to be executed interactively. 

Holds the address of the keyboard input circular buffer. 



Used to hold the return stack pointer which is saved away 
before compilation and checked after compilation. 



diskerror# Holds the most recent disk error number. 
drive Holds the number used to specify the drive type. 
Holds count for the disk countdown timer. 



dticks 
edde 

end table 

execbuf 

extant 

gticks 

gvect 

here 



I/O flag. If true (nonzero) output should be sent to the 
editor. 

Holds the end address of the RAM token table. 



Holds the address of the vocabulary 'extant* array. 

Holds count for a general countdown timer. 

Used as a general execution vector. 

Holds the address of the next available location in the 
code area of the current open vocabulary. 
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hid 



in 



During number formatting, holds the current offset into the 
string being constructed in the pad. 

Pointer used to mark word's progress through the input stream. 
in always holds the address of the next byte to be examined by 
word in the input stream. 



intexecvecs Interrupt execution vectors, 
inuse 



itx 
jdn 
kev 



Holds the address of the current input text. 



kstat 

kval 

last^thline 

lasttok 

len 

limit 

locals 



localvoc 



location 



loops 



lp 



maxblks 



Holds the length of the word most recently extracted from the 
input stream by word . 

Used to hold the end address of the block of text to be 
examined by the word interpret. 

Used during the compilation of local variables to keep track of 
the amount of local variable return stack storage space which 
is required by the definition currently being compiled. Used 
primarily by the words doloc , local , and ; . 

Holds the address of the temporary hidden vocabulary used 
to hold the names of local vocabularies . 

Used during the compilation of local variables to hold the 
address of the special, invisible vocabulary used to hold the 
names of the local variables used by the word currently 
being compiled. 

System integer used during the compilation of a 'do' loop 
program control structure to hold the amount of return stack 
space currently required by the definition being created. 
Used primarily by the words do , loop , +loop , doloc , 
and ; . 

I/O flag. If true (nonzero) output should be sent to the 
line printer. 
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modifiers 
nesting 



nestype 



newest 

origin 
pad 



panicked 
r amend 
rams tart 



System state flag, if true (nonzero) the system is in a 
temporary compiling state (for interactive execution of 
program control structures). If false (0) the system is in 
the interpreting s t ate . 

The nestype system integer is used to hold a flag which, 
during the compilation of program control structures, holds 
a * -1' if the program control structure currently being compiled 
is a 'do' loop or holds a '0* if the program control structure 
being compiled is a 'begin' loop. Used by the compiling word 
{while} . 

Holds the header address of the most recently defined colon 
definition. 

Holds the address of the start of the 'tFORTH' dictionary. 

Holds the address of a location 128 (decimal) bytes from the 
start of a 384 (decimal) byte scratch location. The pad area 
is used by the number formatting operators and by the editor 
[CALC] function. 



Holds the address of the end of RAM memory. 
Holds the address of the start of RAM memory. 



ringsoundaddr 

Holds the address of a general ring sound routine. 



savenest 
saves tate 
scontcopy 
screen 
screensize 



ser 



Holds the address of the start of display memory. 



I/O flag. If true (nonzero) output should be sent to the 
serial port. 



soundaddr Holds the address of a general sound routine . 

soundcount Holds general sound count. 

spO Holds the address of the base of the parameter stack. 

special Holds the address of the keyboard 'special' array. 
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state 



str 



strings 
targeting 
ticks 
tokens 



top 

vdelay 

vticks 



System state flag, if true (nonzero) system is in the compiling 
state. If false (0) the system in the interpreting state. 

Each time word gets the next word frc; input string, it 
places the address of the character string in the str system 
integer. See the description for the system integer len also. 



Flag. If true (nonzero) target compilation is occurring. 

Holds time ticks. 

One of two system integers used to help in the assignment of 
tokens to new words ( lasttok is the other system integer used 
for this purpose). See the techical discussion on local 
variables. 

Holds the address which is one byte beyond the top of 
'tFORTH' memory. 

Holds the value used to specify how long the video screen 
should stay 'on' on an unused terminal. 

Holds count for the video countdown timer. 

Holds 'tFORTH's column output position. 

Holds 'tFORTH's row output position. 
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tFORTH GLOSSARY 
(Alphabetic Listing) 

! { n a - ) 

('store') 
Stores the 32-bit value n into memory starting at address a. 

Ichar ( char - ) 

Takes a character returned by <?k> , stores the character 
code in the system integer char t and stores a true (nonzero) 
value in the system integer char? to indicate that a character 
is available. 

!csp ( - ) 

( 'store-csp' ) 

Saves return stack pointer during compilation. 

Iptr ( n delta - ) 

Store the value n into the save block area. 

" Compile time: ( - ) 

( 'quote' ) 

Run- time: ( - addr len ) 
Format: " ccc" 

Compiling, lays the string between quotes, and the runtime 
code <">, into the definition being compiled. At runtime the 
address and length will be left on the parameter stack. 

"to ( addrl nl addr2 n2 - ) ('quote-to') 
Format: " ccc" < string name> "to 

Stores the string specified by the address and length (addrl 
and nl) into the string integer specified by name. addr2 and 
n2 are discarded. 

# ( nl - n2 ) 

( ' sharp ' ) 

Format: n <# ... # ... #> 

Extracts the lowest order digit from the number on top of the 
stack and inserts it into the formatted numeric string being 
constructed in the pad. 

#> ( nl - a n2 ) 
( ' sharp -greater' ) 
Format: n <# ... #> 
Prepares a formatted numeric string for type. 

#s ( n - ) 
( ' sharp-s ' ) 

Format: n <# ... #s ... #> 

Calls # until the number on top of the stack has been reduced 
to zero. 
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' ( - token ) 

('tick') 

Format: * <name> 
Returns the token for <name>: 

( ( - ) 

( * paren ' ) 

Format: ( ccc ) 

All characters between the starting left paren and the closing 

right paren are considered to be comments and are ignored by 

the FORTH compiler. 

♦ { nl n2 - n3 ) 
( ' times ' ) 

Multiplies nl*n2 and leaves the 32-bit result n3. 

+ { nl n2 - n3 ) 

(♦plus*) 
Adds nl plus n2 and leaves the 32-bit result n3. 

♦ ! ( n a - ) 

{ 'plus-store 1 ) 

Adds the 32-bit value n to the 32-bit value located in memory 

starting at address a. Memory at a is modified. 

+bit7 ( char - char' ) 
{'plus-bit-?') 
Sets the seventh bit in the character byte. 

♦loop Compiling: { - ) 
( 'plus-loop' ) 
Executing: ( n - ) 
Format: do ... n +loop 

Program control structure used to implement definite loops. 
During execution, +loop adds 'n' to the current loop index. 

♦ table { n - a ) 

{'plus- table' ) 

Converts a token table entry number to the token table entry 

fields address. 

+to ( nl n2 - ) 
{'plus- to' ) 

Format: nl <integer or local variable name> +to 
Adds nl to the current value of the integer or local variable 
specified by name. 

{ n - ) 

{ ' comma * ) 

Lays the 32-bit value 'n' into the next free location in the 

code area. The here pointer always points at the next free 

location in the code area. The here pointer is incremented by 

4 bytes. 
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( nl n2 - n3 ) 

( * minus ' ) 

Subtracts n2 from nl and leaves the 32-bit result on the stack. 

-1 ( - -1 ) 

( * minus -one ' ) 

Puts the constant value '-1' on top of the parameter stack. 

-trailing ( addr len - addr len' ) 
( 'minus- trailing* ) 
Strips the trailing spaces from the string located at address. 

-userounded 

( n - ) 

{'dot') 

Prints the signed value on top of the stack followed by a 

trailing space. Prints in the current radix. 

( - ) 

{ 'dot-quote' ) 

Format: ." ccc" 

May be used interactively or compiled into a definition. The 

compile- time action of . " is to lay the string between quotes 

into the definition being compiled. The run-time action of . " 

is to type the string between quotes out to the current output 

device. 

.r ( n w - ) 
('dot-r') 
Prints the signed value 'n 1 in a field which is 'w' spaces wide, 

• s ( - ) 

('dot-s') 

A nondestructive display of the items on the parameter stack. 

/ ( nl n2 - n3 ) 

('divide') 
Divides nl by n2 and leaves the 32-bit quotient on the stack. 

/mod ( nl n2 - n3 n4 ) 
{ 'divide-mod' ) 

Divides nl by n2 and leaves the 32-bit remainder, n3, and the 
32-bit quotient, n4, on the stack. 

( - ) 

( 'zero' ) 
Puts the constant '0' on top of the parameter stack. 

0< ( n - f ) 

( ' zero-less-than' ) 

Returns a true (-1) flag if n is less than zero. 
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0= 



1* 



1- 



2* 



2- 



2/ 



2drop 



2dup 



3dup 



n - f ) 
* zero-equal ' ) 
Returns a true (-1) flag if n is equal to zero. 

- 1 ) 

Puts the constant '1' on top of the parameter stack. 

nl - n2 ) 
'one-plus* ) 
Adds one to the number on top of the stack. 

nl - n2 ) 
'one -minus' ) 
Subtracts one from the number on top of the stack. 

nl - n2 ) 

' two-times ' ) 
Multiplies the number on top of the stack by two. 

nl - n2 ) 
' two-plus ' ) 
Adds two to the number on top of the stack. 

nl - n2 ) 
' two-minus ' ) 
Subtracts two from the number on top of the stack. 

nl - n2 ) 
' two-divide ' ) 
Divides the number on top of the stack by two. 

nl n2 - } 
' two drop ' ) 
Discards the top two items on the parameter stack. 

nl n2 - nl n2 nl n2 ) 
' two dup ' ) 
Duplicates the top two items on the parameter stack. 

nl n2 n3 - nl n2 n3 nl n2 n3 ) 
' three -dup' ) 
Duplicates the top three items on the parameter stack. 

- ) 
'colon' ) 

Format: : <name> ...words... ; 

Defining word used to create new definitions. Puts the system 
in the compiling state, creates a new dictionary header using 
<name> , sets the smudge bit in the dictionary header so the 
definition will not be visible until completed. 
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<"> 



< M to> 



( - ) 

( 'semi-colon* ) 

Used to terminate colon definitions. If the colon definition does 

not use local variables, : causes the word <;> to be compiled 

into a definition. If the colon definition does use local 

variables, ; causes the word <;lp> to be compiled into a 

definition. 

( nl n2 - f ) 

('less-than') 

Returns a true (-1) flag is nl is less than n2. 

( - addr len ) 

( 'brac-quote' ) 

<"> is the run-time code for the word " 

and length of the string on the stack. 

( addrl nl addr2 n2 -> addr3 n3 ) 

( 'brac-quote-to' } 

Run- time code for "to . 



Pushes the address 



<# ( n - n ) 

( 'less-sharp' ) 

Format: n <# ... #> 

Marks the start of a pictured numeric conversion process. 

<+loop> ( n - ) 

( 'brac-plus-loop' ) 

Run- time code for +loop . 

<Obran> ( f - ) 

{ 'brac-zero-bran 1 ) 

Run-time conditional branching primitive. A branch will occur 
if the flag passed to <0bran> is false (zero) . Can only 
handle short (-8l<n<80 hex) branching distances. Used by 
while, until, and if. 



<0branl> ( f - ) 

( 'brac-zero-bran-long' ) 

Run- time conditional branching primitive. A branch will occur 
if the flag passed to <Obranl> is false (0) . Can be used for 
short and word (-8001<n<8000 hex) branching distances. Used 
by while , until , and if . 



<01eave> 



( f - ) 

( 'brac-zero-leave' ) 

Run-time code used to conditionally leave from a 'do... loop' 

or 'do...+loop' program control structure. 



<01eavel> 



( f - ) 

( 'brac-zero-leave-long' ) 

Run- time code used to conditionally leave from a 'do 

or 'do...+loop' program control structure. 



loop' 
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<;> 



<;lp> 



<<?k>> 



<> 



<?k> 



<abort M > 



<addto> 



Parameter: { - ) 

( ' brac-semi ' ) 

Return: ( nl n2 - ) 

Run- time word compiled by ; . 



- ) 
'brac-semi-local' ) 

Run- time exit word compiled at the end of colon definitions 
in which local variables are used. Compiled by ; . 

- flag ) 

' brac-brac-question-k' ) 
Returns a true (nonzero) flag if a key is available. 

nl n2 - f ) 
'not -equal' ) 
Returns a true (-1) flag if nl is not equal to n2. 

- f ) 
'brac-question-k' ) 

Uses <<?k>> to see if a key is available and returns a true 
nonzero) flag if a character is available. 

fan-) 
'brac-abort-quote' ) 
Run-time code used by abort" . 

n - ) 
' brac-addto' ) 
Close the current open vocabulary and open the vocabulary 
specified by the token 'n' . 



<avg> 
<becode> 

< behead > 



( n - ) 

( ' brac-becode ' ) 

Remove the code corresponding to the token 'n' . 

( a - ) 

( 'brae -behead ' ) 

Remove the header located at address 'a'. 



<bevoc> ( n - ) 

( * brac-bevoc ' ) 

Completely eliminate the vocabulary specified by the token 'n 

<bran> { - ) 

{ 'brac-bran' ) 

Run- time unconditional branching primitive. Always causes 
a branch to occur. Can only handle short (-8l<n<80 hex) 
branching distances. Used by again and else . 
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<branl> { - ) 

( 'brac-bran-long' ) 

Run- time unconditional branching primitive. Always causes 
a branch to occur. Can handle short <-8l<n<80 hex) and 
word (-8001<n<8000) length branching distances. Used by 
leave and else . 



<csize> ( a - n ) 

( * brac-code-size ' ) 
Returns the code size 
is located at address 



in bytes, of the word whose code 



<deact±vate> 



<demit> 



<do> 



( 'brac-deactivate' ) 

< n - ) 

Removes the vocabulary specified by the token 'n' from the 

current search order (removes its token from the 'active 1 

array , see active ) . 

{ char x y - ) 

( 'brac-display-emit 1 ) 

Draw the character at position x,y on the screen. 

( nl n2 - ) 

( 'brac-do' ) 

Run- time code for do . 



<empty> 



<eta> 



<exit> 

<exitlp> 

<find> 



( n - ) 

{ ' brac-empty 1 ) 

Purges all words from the vocabulary specified by the token 



) 



{ a n - | If token 'n 1 is not found. 

{ al n - a2 | If token r n' is found. ) 

Takes the vocabulary address * al ' and the encoded token 

value f n' and, if successful, returns the encoded token address 

( 'brac-exit' ) 

( 'brac-exit-lp* } 

( al a2 nl - a2 f | If not found ) 
{ al a2 nl - a3 n2 t | If found ) 
('brae- find') 

Searches for the name specified by the string at address 'a2 1 
of length 'nl' in the vocabulary which starts at address 'al 1 . 
If the word is found in the vocabulary, <find> will return the 
dictionary header address *a3 f for the word, the token for the 
word *n2' and a true flag (nonzero). If the word is not found 
in the vocabulary <find> will return the original name string 
address 1 a2 1 and a false (zero) flag. 
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<key> 



<leave> 



( - char ) 

( 'brac-key* ) 

Get a key, set char? to zero to indicate that no keys are 

currently available, and, if the system is in the middle of 

recording a learn sequence, record the character. 



( - ) 

( 'brae -leave' ) 

Run-time code used to unconditionally leave from a 'do. 

or 'do...+loop' program control structure. 



. loop * 



< leave 1> 
<load> 



( n - ) 

( 'brac-load' ) 

Reads block 'n* from disk into memory and interprets its 

contents . 



<locO> { - n } 

( 'brac-loc-zero' ) 

A special fast word used to access the first local variable 

on the return stack. 

<locl> ( - n ) 

{ 'brac-loc-one' ) 

A special fast word used to access the second local variable 

on the return stack. 

<local> ( - n ) 

( 'brac-local 1 ) 

Generic word used to access the third, and all subsequent local 

variables on the return stack. 

<locals> ( - ) 

( 'brac-locals* } 

First local variable word compiled into a tForth word which 

uses local variables. 

<loop> ( - ) 

( 'brac-loop' ) 

Run-time code for loop. 

<purge> ( n - ) 

( ' brac-purge' ) 

Removes the word corresponding to the token ' n' from the 

dictionary. 

<quit> ( - ) 

( 'brac-quit' ) 

Low-level word used by quit. 
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<rblock> ( addr b# - flag ) 
( 'brac-r-block' ) 

Read block number 'b' into the buffer located at address 
'addr*. If no error occurs during read, the flag returned will 
be false (0). 

<step> ( - ) 

( 'brac-step' ) 

Step the drive head with interrupts off. Saves and restores 

the status register. 

<string> ( - addr len ) 
{ 'brac-string' ) 

Run- time code for string integers created with the defining 
word string. Pushes the address and length of the string 
stored in the string integer on the stack. 



<sum> 

<sumrounded> 

<wblock> 



<word> 



( a n - f ) 

( 'brac-write-block' ) 

Write the block of data contained in the buffer located 

at address 'a' to block number ' n' on the disk. 

If no error occurs during the write operation the flag 

returned will be false (0) . 

( addrl addr2 - addr3 n addr4 ) 

( ' brac-word' ) 

Lower-level routine used by word. 

( nl n2 - f ) 

( 'greater- than' ) 

Returns a true (-1) flag if nl is greater than n2. 



{ nl n2 - f ) 

{ ' equal ' ) 

Returns a true (-1) flag if nl is equal to n2. 



>r 



( nl - I return stack: - nl ) 

('to-r') 

Removes nl from the parameter stack and places it on the 

return stack. 



?auto 



( - f ) 

( 'question-auto' ) 

Returns a true (nonzero) flag if it is time to autorepeat 

the current character. 
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?csp 



?ctl 



?diskerror 



( - ) 

( 'question-csp' ) 

Compares the current return stack pointer to the return stack 

value saved away previously in the csp system integer. If the 

two addresses are not equal the system will abort with an 

"unpaired" message. 

{ - f ) 

( ' question- control ' ) 

Returns a true (nonzero) flag if one of the use-front 

keys is currently down. 

( n - ) 

( ' question-disk-error ' ) 

?diskerror will take the error code from the parameter stack, 

analyze it, and print an error message which tells the user 

what type of disk error occurred. 



?dup 



?ev 



?k 



(n-nn) or (0-0) 

{ 'question-dupe' ) 

Duplicates the value on top of the stack if it is nonzero. 

{ - f ) 

{ ' question-event ' ) 

Returns a true (nonzero) flag if the keyboard event queue 

is not empty, if keyboard events are available. 

( - f ) 

( 'question-key' ) 

Return a true (nonzero) flag if the current character is not 

a special key. 



?keystep 
?kval 



( - c ) 

( 'key-value' ) 

Returns the character code stored in char . Used to "peek" 

at the current character without affecting its current character 

status. 



?lex 



( - f ) 

( 'question-left-leap* ) 

Returns a true (nonzero) flag if the left leap key is currently 

down. 



?pairs ( - ) 

( 'question-pairs' ) 

Checks for properly paired conditional statements. Aborts 

with an error message if conditionals are improperly paired. 

?panic ( - f ) 

( ' question-panic' ) 

Returns a true flag if the user hit the panic stop key. 
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?rex ( - f ) 

{ * question-right-leap ' ) 

Returns a true flag if the the right leap key is down. 

?shift ( - f ) 

( 'question-shift' ) 

Returns a true flag if either of the shift keys is down. 

?stack ( - f ) 

( ' question- stack* ) 

Checks the status of the parameter stack. A false (0) flag 

will be returned if the stack is ok. 

?stackerr { - ) 

( ' question-stack-error) 

Uses ?stack to check for stack underflow or overflow. 



?t 



@k 



@ptr 



( - f ) 

( ' question- terminal ' ) 

Returns a true (nonzero) flag if a character is currently 

available. The character is consumed by ?t . 

( a - n ) 

('fetch') 

Places a copy of the 32-bit value located in memory starting 

at address a on top of the parameter stack. 

( - c ) 

('fetch-key' ) 

Returns the next 'physical' character (the character code as 

returned by do-event) . 

( n - a ) 

( ' fetch-pointer 1 ) 

Get a pointer from the system id area. 



aabs 

abort 

abort" 



( f - ) 

( 'abort-quote' ) 

Format: f abort" ccc" 

If the flag passed to abort" is true (nonzero) , a forced 

system abort process will occur. 



abs 



addr 



( n - |n| ) 

( 'absolute' ) 

Returns the absolute value of the number on top of the stack. 

( <name> - a ) 

('adder') 

Format: <name of integer> addr 

Returns the address of the storage location for the integer 

specified by name. 
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add to 

afilter 
again 

aint 
align 

allot 
and 
and I 



arithmetic 



array 



ascii 



assign 



asqrt 
backelse 

becomes 



( " ) 

Format: addto <vocab-name> 

Opens the vocabulary whose name immediately follows addto . 



( - ) 

Format : begin . . . again 

Used to implement endless loops. 



{ ~ ) 

Aligns the here pointer to an even address boundary. 

{ n - ) 

Tries to allocate 'n* bytes in the code area of the currently 

open vocabulary. 

{ nl n2 - n3 } 

Performs a bit-by-bit logical AND using nl and n2. Returns the 

32-bit result (n3) on the parameter stack. 

( b a - ) 

( * and-store' ) 

Performs a bit-by-bit logical AND operation using b and the 

byte located in memory starting at address a. The byte at 

address a is modified. 



Name of the vocabulary in which the basic arithmetic functions 
are located. 

Compiling: ( n - ) 

Executing: ( - a ) 

Format: n array <arrayname> 

Create an array of length n and name <arrayname>. Later use 

of <arrayname> will return the address of the start of the array 

( - n ) 

Format: ascii <char> 

Returns the ascii value of <char> . 

( al a2 n - ) 

Assigns a token to and builds a header for a new definition 
in the vocabulary specified by the address ' al' using the name 
located at the address ' a2' with the length 'n'. 



( nl - n2 nl ) 

Used by then to backpatch a forward else branch offset. 

( - ) 
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beep 
begin 
begin 
behead 



bevoc 



blit 



block 



c! 



c, 



eg 



( - ) 
Make a beep. 

( - ) 

Format : begin . . . again 

until 

Used to mark the start of an endless or indefinite program loop 

( - ) 

Format: behead <name> 

Remove the header of the definition whose name immediately 

follows behead . 

( - ) 

Format: bevoc <name of vocabulary> 

Removes the vocabulary name and all its words. 

( - n ) 

('byte-literal 1 ) 

Byte length version of lit. 

( n - ) 

Tries to read block *n' into memory. If block *n' has 

already been read into the block buffer, block will do 

nothing. 

( b a - ) 

{ 'c-store 1 ) 

The least significant 8 bits of the 32-bit value, b, on the 

parameter stack are stored into memory starting at address a. 

( - a ) 

Cc-tick') 

Format: c' <name> 

Leaves the address of the code field of <name> . 

( c - ) 

{ 'c-comma 1 ) 

Compiles the byte value 'c' into the next available 

location in the code area. 

{ a - b ) 

('c-fetch') 

Places the 8-bit value from address a on the stack. 



call 
check 



(an-) 

Format: <string integer name> check 

Prints the ascii values for each character in the string 

currently stored in the string integer specified by name. 

If the string integer is empty, an error message is displayed 
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clear-auto ( - ) 

Turn off autorepeating. 

clr-kbd ( - ) 

( ' clear-keyboard ' ) 

End playback of a learn sequence. 

els ( - ) 

( ' clear-screen ' ) 

Clear the display screen. 

croove ( al a2 u - ) 
( ' c-move 1 ) 

Moves the 'u' bytes located starting at the source address 
'al' to the destination address ' a2'. 



compile 
compile , 



( n - ) 

( 'compile-comma' ) 

Lays the token value passed on the stack into the dictionary 

at the current here address. 



copy ( nl n2 n3 - ) 

Copy blocks number 'nl' through *n2' to the blocks starting 
at block number *n3'. 

copyO>0 ( nl n2 n3 - ) 

Copy blocks number 'nl 1 through 'n2' from the source disk to 

the blocks starting at block number 'n3' on the destination disk. 



cr 



create 



createvoc 



( ~ ) 
('c-r') 
Emit a carriage re turn /line feed. 

{ - ) 

Format: create <name> 

Assigns a token to and creates a header entry for <name> in 

the current open vocabulary. 

{ al n - a2 ) 

Create an empty vocabulary using the image of an empty vocabulary 
located starting at address 'al' and assign it the token ' n' . 
Returned address 'a2' is unused. 



crlfscroll { - ) 

Emit a carriage return and linefeed. Blank the new line out and 
scroll if necessary. 

csize { - n ) 

( 'code-size' ) 

Format: csize <name> 

Returns the code size of the word specified by <name> . 
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ctl 



{ - ) 

( ' control ' ) 

Format: ctl <char> 

Make <char> a control character, 



deactivate ( - ) 

Format: deactivate <vocab-name) 

Removes the vocabulary whose name immediately follows 

deactivate from the current search order. 



decimal 



decode 



demit 



depth 



( - ) 

Set the base to ten. 

( nl - n2 ) 

Turns an encoded token number into a decoded token number, 

( c - ) 

( 'display-emit' ) 

Emit the character to the screen. If the character is a 

cr perform a carriage return/ linefeed and scroll if necessary, 

If the character is the 'del' (delete) character erase the 

previous character on this line (if any) . 

( - n ) 

Returns the number of items on the stack. 



diff? 



( al a2 n -> 1 If strings match ) 
( al a2 n -> a3 -1 1 If strings don't match ) 
Compares the first 'n' characters in the strings located at 
addresses 'al' and t a2 t . 



digit 



do 



do- event 



( nl n2 - n3 c ) 

Extracts the least significant digit from the number, nl , on 
the stack (using the specified base, n2) and leaves ascii value 
for the digit, c, and the remaining number, n3 on the stack. 

Compiling: ( - ) 

Executing: ( nl n2 - ) 

Format: nl n2 do ... loop 

nl n2 do ... n3 +loop 

Marks the start of a definite program loop. 

( - ) 

Removes a key event from the keyboard event queue and converts 

the event code into offset. The offset is used to index into a 

table which converts key press information into character 

information. 



doff 



doloc 



( " ) 

Tries to turn the disk drive(s) off. 

{ - f ) 

('do-local') 

Used by interpret . Checks to see if the word just extracted 

from the input stream belongs to a local variable. 
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don 



down? 



drop 
dump 

dup 

ebuf 
eemit 

else 



emit 



empty 



emptyvoc 



encode 



( " ) 

Tries to turn the disk drive (s) on. 

( n - f ) 

Checks to see if the special key corresponding to the number 
*n' is currently down. Returns a true (nonzero) flag if the key 
is down. 

( nl - ) 

Discards the top item from the stack. 

(an-) 

Displays the contents of 'n' bytes of memory starting at 

address 'a' . 

( nl - nl nl ) 

Duplicates the value on top of the stack. 



( c - ) 

( 'editor-emit 1 ) 

Emit the character to the editor. 

Compiling: ( - ) 

Executing: ( f - ) 

Format: if ... else ... then 

Inner decision point in the 1 if .. .else. .. then' conditional program 

control structure. 

( c - ) 

Output the character to all active output devices. 

( " ) 

Purges all words from the current vocabulary. The words in 

the forth vocabulary cannot be purged. 

( - addr ) 

Returns the address of the 18 decimal byte image of an empty 

vocabulary. 

( nl - n2 ) 

Takes the decoded token number from the top of the stack, 
encodes it, and returns the encoded token number on top of 
the stack. 



error 
eta 



( n - a f ) 

Tries to return the address of the token table entry for the 
token. If successful returns the token table entry address and 
a true (nonzero) flag. Otherwise, returns a false (0) flag. 



exa 
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execute 



existing 



exit 



fill 



find 



finish-lex 



fnderr 



format 



forth 



< n - ) 

Executes the word corresponding to the token 

the stack. 



n' passed on 



( - ) 

Displays the names of and parents of all vocabularies. 

( " ) 

Terminates execution of the current definition and transfers 

control to the definition which contains the current definition. 

( a u b - ) 

Format: 'start address' 'count' 'fill character' fill 

Replaces the u bytes located in memory starting at address a with 

the byte value b. 

{ a nl - n2 true 1 If found in search order ) 
( a nl -> false 1 If not found in search order ) 
Searches the through the dictionary (uses the current search 
order) looking for the definition whose name matches the name 
at the address 'a 1 with length 'nl*. 



( 



) 



( ' find-error' ) 

Prints a "can't find 11 error and aborts. 

( - ) 

Formats a disk using the IAI disk format. 

( " ) 

This is the main tFORTH vocabulary. It contains all of the 
'standard' FORTH words supported by tFORTH and all of the 
tFORTH FORTH extension words. Execution of forth will cause 
the forth vocabulary to become the first vocabulary in the 
search order. 



forward 
free token 

froom? 

function 

get( 

getphrase 

goto 

hex 



( " ) 

Prints an "unassigned token" message and aborts . 



( " ) 

Selects base sixteen (hexadecimal) as the current radix, 
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hidden 



hold 



home 



idblock 



if 



immediate 



inrange 



intO 



intl 



int2 



int3 



( " ) 

Vocabulary which contains all of the editor words. 

( c - ) 

Format: <# ... ascii c hold ... #> 

Inserts the character (ascii value) on top of the stack into the 

formatted numeric string currently being constructed in the pad. 

( - ) 

Positions the cursor in the first column of the first row on the 

screen (in the upper left hand corner) . 

( - n ) 

Puts a copy of the top item on the return stack on top of the 
parameter stack. During execution of a do... loop, the top item on 
the return stack is the index for the current loop. 

( - f ) 

Read one of the two edde id blocks. The flag returned will be 

true (nonzero) if an error occurs during the read. 

Compiling: ( - ) ' 

Executing: ( f - ) 

Format: if ... then 

if ... else . . . then 

Marks the start of the 'if... then* or 'if .. .else. . .then' 

conditional program control structures. 

( " ) 

Sets the 'immediate' bit (bit 6) of the most recently defined 
colon definition so that whenever the word is encountered 
during compilation, it will be compiled rather than executed. 

( nl n2 n3 - f ) 

Returns a true (-1) flag if the value nl is greater than or equal 
to the lower limit n2 and less than or equal to the upper limit n3 
(i.e. n2 < nl < n3 ) . 

( - n ) 

('int-O') 

Runtime code for integers located in integer tier 0. 

( - n ) 

('int-l») 

Runtime code for integers located in integer tier 1. See intO. 

( - n ) 

('int-2') 

Runtime code for integers located in integer tier 2. See intO. 

( - n ) 

rint-3') 

Runtime code for integers located in integer tier 3« See intO. 
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int4 



int5 



int6 



int? 



int8 



- n ) 
•int-4') 

Runtime code for integers located in integer tier 4. See into. 

- n ) 

'int-5 1 ) 
Runtime code for integers located in integer tier 5. See intO. 

- n ) 
'int-6') 

Runtime code for integers located in integer tier 6. See intO. 

- n ) 
•int-7*) 

Runtime code for integers located in integer tier 7« See intO. 

- n ) 
f int-8') 

Runtime code for integers located in integer tier J, See into. 



integer 



interpret 



Compiling: { n - ) 

Executing: ( - n ) 

Format: n integer <integername> 

At compile-time integer creates a named 4-byte data location 

and initializes the location with the value 'n' . The run- time 

action of the child words created by integer is to push the 

current contents of their 4-byte storage location on the stack. 

( a 1 - ) 

interpret parses words in the input stream and either executes 
them (if they are executable Forth words), places them on the 
stack (if they or numbers), or aborts if it does not know what 
to do with the word. 



in te rpre tphras e 
invoc 



ioff 



( a - n ) 

Returns the token 'n' of the vocabulary which contains address 

( ~ ) 

Turns interrupts off. 



ion 



key 



( - ) 

Turns interrupts on. 

( - c ) 

Waits until a printable character (8<ascii code<7F) is typed at 

the keyboard. Returns the ascii value of the character on the 

stack. 



learnstrings 
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leave 



lit 



( " ) 

Immediately and unconditionally reroutes program execution out of 
the current "looping" program control structure. May be used in 
'begin' loops or in 'do' loops. 

( - n ) 

Code definition which transfers the long-word (32-bit) literal 
value pointed to by the instruction pointer to the parameter 
stack. The instruction pointer, ip, is incremented by 4 bytes. 
Used by literal . 



literal ( n - ) 

literal is used to compile constant data into a definition, 
literal will also compile the token of a word which will push 
the constant data onto the parameter stack when the definition is 
later executed. 



load 



( n - ) 
Loads block 



n' from the disk. 



local 



( " ) 

Format: local <name for local variable) 

Creates a named local variable. The local variable is not 

initialized to any value. Executing the name of the local 

variable will place the value of the local variable on top of 

the parameter stack. 



loop 



( - ) 

Format: do ... loop 

Marks the end of the 'do... loop' definite loop program control 

structure. 



max 



min 



mod 



( nl n2 - n3 ) 

Compares nl and n2 and returns the greater value. 

( nl n2 - n3 ) 

Compares nl and n2 and returns the lesser value. 

( nl n2 - n3 ) 

nl is divided by n2 and the 32-bit remainder, n3, is left on 

top of the stack. 



move 



( al a2 u - ) 
Special version of cmove . 



ms 



( n - ) 

Wait 'n' milliseconds. 



( - a ) 

('n-tick') 

Format: n ! <name> 

Returns the address of the dictionary header area for the 

word specified by <name> . 
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name 

needforth 
need text 
negate 

nest 

nip 
noop 
noroom 
not 



not! 



number 



numerical 
oddadjust 
off 



on 



( n - ) 

Print the name of the definition which corresponds to 

the token 'n* . 



( n - -n ) 

Returns the two's complement of n, i.e. 'n' is subtracted from 

zero (0-n) . 

( - ) 

Used by all words which start program control structures. 



( nl - n2 ) 

Takes the ones complement of the 32-bit value on top of the 
parameter stack. Returns the 32-bit result on top of the 
parameter stack. 

( a - ) 

( 'not-store' ) 

Takes the one's complement of the 8 bits of data located in 

memory starting at address a. The byte length result is stored 

into memory at address a. 



{ a nl n2 - f | If conversion is not successful. ) 
( a nl n2 - n3 f | If conversion is successful. ) 
Converts the string of length nl located starting at address a 
to a number, n3, using base n2. 



( n - ) 

Format: <name of local variable or integer) off 

Sets the value of the local variable or integer specified by 

name to zero. The value of the integer or local variable 

placed on the parameter stack when the local variable or 

integer name was executed is discarded. 

( n - ) 

Format: <name of local variable or integer) on 

Sets the value of the local variable or integer specified by 

name to negative one. 



open, 
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or 



or! 



outofroom 
over 

packforth 
page 

pemit 

playback 
playback? 

purge 

quit 



r> 



r& 



( nl n2 - n3 ) 

Performs a bit-by-bit logical or using nl and n2. 

Returns the 32-bit result (n3) on the parameter stack. 

( b a - ) 

(*or-store ! ) 

Performs a bit-by-bit logical OR operation using b and the 

byte located in memory starting at address a. The byte length 

result is stored into memory at address a. 



( nl n2 - nl n2 nl ) 

Places a copy of the second item on the stack on top of the stack 



( - ) 

If the screen is the current output device, clears the screen 

and places the cursor in the upper left corner of the screen. 

( char - ) 

( 'parallel-emit* } 

Send the character out through the parallel port. 

( - c ) 

Return the next character to be played back. 

( - f ) 

Returns a true (nonzero) flag if there is a character to play 

back. 

( " ) 

Format: purge <name> 

Removes the word specif ed by <name> from the dictionary. 

( " ) 

quit is the word which runs FORTH. Clears the return stack and 
puts the system in the interpreting state. After quit is 
executed the system will be waiting for user input for user input 
to interpret and execute. 

( n - | return stack: - n ) 

('r-from') 

Transfers the top item on the parameter stack to the top of 

the return stack. 

( - n ) 

(»r- fetch') 

Puts a copy of the top item on the return stack on top of the 

parameter stack. r§ performs the same function as i but r@ 

is normally used outside of do... loops. 
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raddr 



( - a ) 

( * return-address ' ) 

Copies the return information stored on the return stack. 

Uses the return information to calculate the address where the 

next token to be executed in the definition at the next higher 

execution level is located (calculates the previous location of 

the ip pointer) . Used by compile . 



ramchecksum 
recal 



( - n ) 

Recalibrate the disk drive to track 0. 



record ( c - c ) 

Insert the character in the learn string currently being recorded 

recycle ( n - ) 

Reclaims the token table space for the token ' n'. 

recycled token 

( - token ) 

recycledtoken checks to see if any previously assigned tokens 

are now available for re-assignment. 



restore 
re top 



( a - ) 

Lower level word used to open a vocabulary. Moves the upper half 
of the dictionary up so that the new top of dictionary is at 
address 'a' . 



ringoff 
rotnchecksum 



{ - ) 

Turns off timer interrupts. 



rot 

rp! 
rub 

safety 



( nl n2 n3 - n2 n3 nl ) 

('rote') 

Rotates the third item on the stack to the top of the stack. 



( - ) 

Erase the previous character on the current line (if any). 

( a - ) 

Reclaim the token table space for the token whose header 

is located at address 'a'. 



same? 



( al a2 n -> f ) 

Returns a true (nonzero) flag if the first 'n' characters in the 

strings located at 'al' and ' a2' are the same. 
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save? ( - ) 

( * save-question-mark ' ) 

Aborts if the disk is write-protected. 

scan for { c - ) 

Looks for the next word in the current input stream which is 
surrounded by the delimiter character, c. Sets the in , str , 
and len system variables. 



searched 



serai t 



( " ) 

Display the vocabulary search order. 

( c - ) 

( 'serial-emit' ) 

Emit the character to the serial port. 



set-auto ( - ) 

Turn on autorepeating for the last key returned. 

setcodesize ( - ) 

Set the code size field for the current open vocabulary. 
Set the odd size flag if necessary. 



setcur 



shl 



shr 



sideO 



( x y - ) 

Position the cursor at x,y. 

( nl n2 - n3 ) 

{'shift-left') 

Shifts the bits in 'nl' 'n2' bits to the left. Leaves the 32-bit 

result, 'n3 1 , on the parameter stack. 

( nl n2 - n3 ) 

('shift-right') 

Shifts the bits in 'nl' 'n2' bits to the right. Leaves the 32-bit 

result, *n3', on top of the parameter stack. 

( - ) 
Select side 0. 



sidel 



( - ) 
Select side 1. 



sign 



{ n - ) 

If the number on top of the stack is negative, sign will insert 
a minus sign into the formatted numeric string being constructed 
in the pad . 



sp! 
sp£ 
space 



( - ) 

Emit a space to the current active output devices. 



- 235 - 



spaces 
step in 
stepout 
string 



stub 



( n - ) 

Emit *n' spaces to the current active output devices. 

{ - ) 

Set drive to step in. 

( - ) 

Set drive to step out. 



Compiling: (an-) 

Executing: (-an) 

Format: " ccc" string <stringname> 

At compile- time string creates a named, multi-byte string 

storage area in the dictionary and initializes the storage area 

with the characters between the quotes. The run-time action 

of the child words created by string is to push the address 

and length of the string currently stored in the string storage 

area on the stack. 

( - ) 

Format: stub <name> 

Uses create to assign a token to and create a dictionary 

header for <name> . Stores a in <name> ' s token table entry so 

<name> will not have any corresponding code area. 



sw 
swab 

swap 



( nl - n2 ) 

Exchanges the lower two bytes of the top value on the stack. 

( nl n2 - n2 nl ) 

Exchanges the top two items on the parameter stack. 



sync - sh i f tkeys 

{ - ) 

Store the actual physical states of the special keys, as 
stored in the system integer shifts tate , into the modifiers 
system integer. 



temp 
then 



thislearn 



thp 



thru 



( - ) 

Format: if ... then 

if ... else . . . then 

Marks the end of the 'if... then' or 'if .. .else. . .then' conditional 

program control structures. 

(-an) 

Return the address and length of the current learn string. 

( n - ) 

Set up sound generator frequency. 

( nl n2 - ) 

Loads block number 'nl' through block number 'n2' from disk. 
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tier ( - ) 

The first byte of a multi-byte token is called a tier. The 
tiertokens have to be in order. Every 256 definitions in the 
dictionary takes up a new tier in the token table. Those tiers are 
named tierl tier2 tier3 up to tier9 (10 times 256 words in the 
dictionary), tier is never executed alone. 

tip ( a - ) 

Toggles memory or I/O port location. 

to ( nl n2 - ) 

Format: nl <name of local variable or integer> to 
Replaces the current value of the integer or local variable 
specified by name with the 32-bit value nl. The value placed 
on the stack when the local variable or integer name was executed 
is discarded. 

toff ( - ) 

Turn sound generator off. 

ton ( - ) 

Turn sound generator on. 

tone ( nl n2 - ) 

Emit sound with the pitch 'nl' for the duration 'n2' . 
The duration is specified in ticks. 

type (an-) 

Types the ' n' characters located in memory starting at address 
'a' out to the current output device. 

u. ( n - ) 

Prints the unsigned value on top of the stack followed by a 
trailing space. 

u.r ( n w - ) 

Prints the unsigned value 'n' in a field which is ' w' spaces wide. 

u< ( ul u2 - f ) 
( 'u-less-than' ) 

Returns a true (-1) flag if the unsigned value ul is less than 
the unsigned value u2 

unnest { - ) 

Used by all words which end program control structures. 

unpackforth 

until ( f - ) 

Format: begin ... f until 

Conditional exit/branching word used at the end of the 

'begin. . .until* indefinite loop program control structure. 

user ( - ) 

Vocabulary to which all user defined words are added. 
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vocab 



vocab? 



( - ) 

Move the current execution vocabulary to the top of the search 

order by placing its token at the start of the active array. 

( n - f ) 

Returns a true (nonzero) flag if the token on top of the stack it 

the token for a vocabulary. Returns a false (0) flag otherwise. 



vocabulary ( - ) 

Format: vocabulary <vocabname> 
Create a new, but inactive, vocabulary. 



voff 



von 



( " ) 

(♦video-off*) 

Turn the video display off. 

( - ) 

{ 'video-on* ) 

Turn the video display on and off. 



vopen 



wt 



w, 



w@ 



wblock 



wblocks 



( n - a ) 

Returns the address of the opening point for the vocabulary 

which corresponds to the token. 

{ w a - ) 

( 'word-store' ) 

The least significant 16 bits of the 32-bit value, b, on the 

parameter stack are stored into to memory starting at address a. 

( w - ) 

{ 'w-comma' ) 

Stores the word length value 'w' into the next available spot 

in the code area of the currently open vocabulary. 

( a - w ) 

('word- fetch'} 

Places the 1 6-bit value located in memory starting at address a 

in the least significant word of a 32-bit value on top of the 

parameter stack. The upper 2 bytes (16 bits) are set to zero. 

( addr b - ) 

( 'write-block* ) 

Write the block of data located in RAM starting at address 'addr' 

to block number 'b' on the disk. 

( nl n2 ■ n3 n4 ) 

( 'write-blocks' ) 

Write 'nl' blocks, starting with block 'n2 r , to disk from memory 

starting at the address of the here pointer. 
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while 



Compiling: ( - ) 

Executing: ( f - ) 

Format: begin ... while ( ... while ) ... again 

begin . . . while ( ... while ) ... until 

do ... while ( ... while ... ) ... loop 

dO ... while ( ... while ... ) ... +loop 

Inner decision/branching point in the ' begin . . . until ' , 

' begin ... again * t 'do... loop', or 'do...+loop' program control 

structures. 



window 



wlit 



word 



words 



( n - ) 

Set FORTH' s bottom display line to 'n' where K=n<=lD. 

( - n ) 

('w-lit') 

Code definition which transfers the word-length (16-bit) literal 

value pointed to by the instruction pointer to the parameter 

stack and increments the instruction pointer by 2 bytes. Used 

by literal. 

( - ) 

Looks for the next word in the current input stream which is 

surrounded by at least one space. Sets the in, str, 

and len system variables accordingly. 

( " ) 

Displays a list of all words in the vocabulary which is first in 

the search order. 



wtrack (an-) 

( 'write-track' ) 

Write track using IAI format to disk. 

xor ( nl n2 - n3 ) 

Performs a bit-by-bit logical xor using nl and n2 
Returns the 32-bit result on the parameter stack. 



xor! 



['] 



( b a - ) 

{ 'exclusive-or-store' ) 

Performs a bit-by-bit logical XOK peration using b and the 

byte located in memory starting at address a. The byte length 

result is stored into memory at address a. 

( " ) 

('left-bracket' ) 

Turns the FORTH compiler on. 

( - token } 

( 'brac-tick-brac' ) 

Format: : <name> ... ['] < definition -name > ; 

[*] must be used within a colon definition. [•] will return the 

token for the definition whose name immediately follows it 

in the colon definition. 
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[compile] ( - ) 

( 'brac-compile-brac ' ) 

Compiles the token of the word which immediately follows 

it into the definition currently being constructed. 

] (' - ) 

('right-bracket') 

Turns the FORTH compiler off. 

{elsethen} ( ' curly-else-then' ) 

Lower- level compiling word used by else and then. 

{loop} ( nl n2 - ) 
( 'curly- loop* } 

Shared routine used by the loop termination words loop , 
♦loop, until and again. 

{while} ( - ) 

( 'curly-while' ) 

Shared routine used by the words used to exit from loop 

program control structures: while and leave. 
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active 
applic 

auto 
base 

blk 
bound 

cbuff 

char 

char? 

clockO 

clockl 

crt 

csp 

diskerror# 
drive 
dticks 
edde 

end table 

execbuf 

extant 

gticks 

gvect 

here 



tFORTH SYSTEM INTEGERS 
(Alphabetical Listing) 

Holds the address of the 'active' vocabulary array. 

Holds the address of the next available location in the 
header area of the current open vocabulary. 



Holds the number used to indicate the numeric base currently 
being used for all number I/O. 



During the interactive execution of program control structures, 
bound is used to hold the start address of the program control 
structures code which is to be executed interactively. 

Holds the address of the keyboard input circular buffer. 



Used to hold the return stack pointer which is saved away 
before compilation and checked after compilation. 

Holds the most recent disk error number. 

Holds the number used to specify the drive type. 

Holds count for the disk countdown timer. 

I/O flag. If true (nonzero) output should be sent to the 
editor. 

Holds the end address of the RAM token table. 



Holds the address of the vocabulary 'extant' array. 

Holds count for a general countdown timer. 

Used as a general execution vector. 

Holds the address of the next available location in the 
code area of the current open vocabulary. 
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hid 



in 



During number formatting, holds the current offset into the 
string being constructed in the pad. 

Pointer used to mark word's progress through the input stream. 
in always holds the address of the next byte to be examined by 
word in the input stream. 



intexecvecs Interrupt execution vectors. 

inuse 

itx Holds the address of the current input text. 

jdn 

kev 

kstat 

kval 

last^thline 



lasttok 
len 

limit 

locals 



localvoc 



location 



loops 



lp 



maxblks 



Holds the length of the word most recently extracted from the 
input stream by word. 

Used to hold the end address of the block of text to be 
examined by the word interpret . 

Used during the compilation of local variables to keep track of 
the amount of local variable return stack storage space which 
is required by the definition currently being compiled. Used 
primarily by the words doloc, local, and ; . 

Holds the address of the temporary hidden vocabulary used 
to hold the names of local vocabularies. 

Used during the compilation of local variables to hold the 
address of the special, invisible vocabulary used to hold the 
names of the local variables used by the word currently 
being compiled. 

System integer used during the compilation of a 'do' loop 
program control structure to hold the amount of return stack 
space currently required by the definition being created. 
Used primarily by the words do , loop , +loop , doloc , 
and ; . 

I/O flag. If true (nonzero) output should be sent to the 
line printer. 
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modifiers 
nesting 



nestype 



newest 

origin 
pad 



panicked 
r amend 
rams tart 



System state flag, if true (nonzero) the system is in a 
temporary compiling state (for interactive execution of 
program control structures). If false (0) the system is in 
the interpreting state. 

The nestype system integer is used to hold a flag which, 
during the compilation of program control structures, holds 
a * -1' if the program control structure currently being compiled 
is a 'do' loop or holds a '0' if the program control structure 
being compiled is a 'begin' loop. Used by the compiling word 
{while} . 

Holds the header address of the most recently defined colon 
definition. 

Holds the address of the start of the 'tFORTH' dictionary. 

Holds the address of a location 128 (decimal) bytes from the 
start of a 384 (decimal) byte scratch location. The pad area 
is used by the number formatting operators and by the editor 
[CALC] function. 



Holds the address of the end of RAM memory. 
Holds the address of the start of RAM memory. 



ringsoundaddr 

Holds the address of a general ring sound routine. 

savenest 

saves tate 

scontcopy 

screen Holds the address of the start of display memory. 

screensize > ';--v >■■::•:' er f ; tv 



ser 



I/O flag. If true (nonzero) output should be sent to the 
serial port. ;::: r 



soundaddr Holds the address of a general sound routine . 

soundcount Holds general sound count. 

spO Holds the address of the base of the parameter stack. 

special Holds the address of the keyboard 'special' array. 
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state 
str 

strings 
targe tin| 
ticks 
tokens 



top 

vdelay 
v ticks 



System state flag, if true (nonzero) system is in the compiling 
state. If false (0) the system in the interpreting state. 

Each time word gets the next word from the input string, it 
places the address of the character string in the str system 
integer. See the description for the system integer len also. 



Flag. If true (nonzero) target compilation is occurring. 

Holds time ticks. 

One of two system integers used to help in the assignment of 
tokens to new words (lasttok is the other system integer used 
for this purpose) . See the techical discussion on local 
variables . 

Holds the address which is one byte beyond the top of 
'tFORTH' memory. 

Holds the value used to specify how long the video screen 
should stay 'on 1 on an unused terminal. 

Holds count for the video countdown timer. 

Holds ' tFORTH 's column output position. 

Holds ' tFORTH 's row output position. 
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■s.t ffi3,;pv^PP®fPIX.^,,|D|FIHIIfG WORDS 

Defining words are the most powerful of the Forth words because 
they allow the programmer *tp .create new Forth words. The 
defining words which, have been .used so far (although they weren't 
categorized as defining words previously) are : , integer .", 
string , and vocabulary . 

CREATING NEW DEFINING WORDS 

The words < builds and does> are used to create new Forth defining 
words. The word does> (described in "Starting Forth") was not 
included in tForth since the ability to create new defining words 
was not required in the Cat system. However, the second listing 
in the appendix shows three words which, when included. in the 
tForth dictionary, add the ability to create defining words to 
the Cat system. 

The format for creating defining words with these extension words 
is: 



<name> 
<builds 
does> 



. . . compile time actions . . 
...execution time actions 



(Note that in Chapter 11 of "Starting Forth" the word create is 
used in place of the word <builds.) Here is how the 'characters' 
example found on page 293-295 of "Starting Forth" could be 
implemented using <builds and does> : 



characters ( n 
<builds 

dup , 



) 



allot 



does> 



dup 
4 * 



swap € 



Creates a new dictionary entry. } 
Compile the count into the first. 
Position in the child word's. ) 
Parameter field for future ) 
reference. ) 

Allocate count bytes in the code ) 
area for the string characters. ) 
Marks the beginning of the run- ) 
time code, leaves the parameter ) 
field address of the child word ) 
on the stack at run-time. ) 
Copy the parameter field address . 
Advance the address past the ) 
four byte count value to the ) 
actual start of the string. ) 
Swap the string address with the ) 
count addr and fetch the count ) 
value from the count address. ) 



20 characters me 
me . . 20 479AO 
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hex 



When the child word created by characters ( me in the above 
example) is executed, it returns the length of its character 
array and the address of its character array on the stack. 

Defining the word words: 



integer doesptr 



( holds the address of where to patch token 



<buiids { - ) 

create { 
4ED3 w, { 

hare doesptr to 
w s ( 



create the new name ) 
it will do a nest ) 

( remember where the token should go ) 
and make space for it } 



<does>> ( - } 
raddr 

doesptr wl 



( terminate this word and get token addr ) 
( find the compiled token ) 
{ and back patch it ) 



does> { - ) 

recycledtoken ( allocate a token ) 
dup -1 = 

abort" out of tokens" 
dup 100 < 

abort" must be a 2 byte token" 
lasttok to ( 
compile <does>> ( 
lasttok w, ( 
align ( 



( and test it first ) 



remember which token it was ) 
compile the runtime version of does> ) 
and the token for the does> code ) 
align here pointer on even address ) 

here lasttok *table ! ( and store address of does> part in table ) 

4ED3 w, ( nest the does part ) 

compile raddr ( so doesn't return and so data address is ) 
( on stack ) 



iamediaie 

test ( n — | n — addr \ compiles an array with n entries 
runtime takes an entry number and returns the addr for it } 
<builds k * allot ( allocate space ) 
does> 

swap ( calculate address ) 

4 • ♦ ; 
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